errors transactions

Transactions errors

Guide to troubleshooting Transactions errors

TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION

Transaction data was updated during pagination.
Common causes
  • Transaction data was updated during pagination. This can occur when calling the /transactions/sync endpoint.
Troubleshooting steps
1http code 400
2{
3 "error_type": "TRANSACTIONS_ERROR",
4 "error_code": "TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION",
5 "error_message": "Underlying transaction data changed since last page was fetched. Please restart pagination from last update.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

auth partnerships sila money

Add Sila Money to your app

Use Sila Money with Plaid Auth to send and receive payments!

Partnership Sila Money logo

Overview

What can you do with the Sila API?

The Sila API endpoints enable you to:

  • Same-day pre-approval for US registered companies operating in regulated industries
  • Create digital wallets for your end-users with underlying funds held in FDIC Member bank
  • Store value using SILAUSD in digital wallets and transfer money compliantly in the U.S.
  • Verify individual and business identities compliant with U.S. KYC & KYB regulations
  • Link bank accounts, check balances, and identify owners via our partnership with Plaid
  • Perform ACH debit and ACH credit transfers for U.S. citizens and permanent residents
  • Program your app's money using business logic or self-executing smart contracts

Why use the Sila API?

The Sila API was designed to help you:

  • Off-board your U.S. compliance requirements
  • Decrease your go-to-market time and upfront costs
  • Reduce the number of APIs and vendors you use
  • Minimize fraud using Sila's proprietary scoring models
  • Move money 24/7 in real-time using SILAUSD

Sila offers SDKs in JavaScript, Node, Python, .NET, and PHP as well as a Postman collection and API explorer demo application.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Sila Money account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Sila Money processor_token, which allows you to quickly and securely verify a bank funding source via Sila Money's API without having to store any sensitive banking information. Utilizing Plaid + Sila Money enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Sila Money in order to use the Plaid + Sila Money integration. You'll also need to enable your Plaid account for the Sila Money integration.

First, you will need to work with the Sila Money team to sign up for a Sila Money account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Sila Money to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Sila Money processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Sila Money, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Sila Money processor_token. You'll send this token to Sila Money and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Sila Money processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'sila_money',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

You can work with Sila Money in either Sandbox (sandbox.plaid.com, allows testing with simulated users) or Production (production.plaid.com, requires Sila Money Production credentials). While Plaid also has a third environment, Development, processor tokens created in that environment are not compatible with Sila Money.

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Sila Money Production credentials prior to initiating live payment transactions in the Sila Money API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

account

Account Overview

Learn about your Plaid developer account

Developer account overview

Your Plaid developer account is managed through the developer dashboard.

image of Developer Dashboard

This section provides information on topics related to managing your Plaid developer account, such as billing, account security, and team membership. You can also find information on logging and troubleshooting in the dashboard, including institution status details and logs of API activity on your account.

A Plaid developer account is different from a Plaid account at my.plaid.com. To manage the financial information you're sharing via Plaid, visit my.plaid.com.

api products payment initiation

Payment Initiation (UK and Europe)

API reference for Payment Initiation endpoints and webhooks

Make payment transfers from your app. Plaid supports both domestic payments denominated in local currencies and international payments, generally denominated in Euro. Domestic payments can be made in pound sterling (typically via the Faster Payments network), Euro (via SEPA Credit Transfer or SEPA Instant) and other local currencies (Polish Zloty, Danish Krone, Swedish Krona, Norwegian Krone), typically via local payment schemes.

For payments in the US, see Transfer.

Looking for guidance on how to integrate using these endpoints? Check out the Payment Initiation documentation.

Endpoints
/payment_initiation/recipient/createCreate a recipient
/payment_initiation/recipient/getFetch recipient data
/payment_initiation/recipient/listList all recipients
/payment_initiation/payment/createCreate a payment
/payment_initiation/payment/getFetch a payment
/payment_initiation/payment/listList all payments
/payment_initiation/payment/reverseRefund a payment from a virtual account
/payment_initiation/consent/createCreate a payment consent
/payment_initiation/consent/getFetch a payment consent
/payment_initiation/consent/revokeRevoke a payment consent
/payment_initiation/consent/payment/executeExecute a payment using payment consent

Users will be prompted to authorise the payment once you initialise Link. See the documentation for link/token/create for more information on how to obtain a payments link_token.

Webhooks
PAYMENT_STATUS_UPDATEThe status of a payment has changed

Endpoints

/payment_initiation/recipient/create

Create payment recipient

Create a payment recipient for payment initiation. The recipient must be in Europe, within a country that is a member of the Single Euro Payment Area (SEPA) or a non-Eurozone country supported by Plaid. For a standing order (recurring) payment, the recipient must be in the UK.
It is recommended to use bacs in the UK and iban in EU.
The endpoint is idempotent: if a developer has already made a request with the same payment details, Plaid will return the same recipient_id.

payment_initiation/recipient/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
name
requiredstring
The name of the recipient. We recommend using strings of length 18 or less and avoid special characters to ensure compatibility with all institutions.

Min length: 1
iban
string
The International Bank Account Number (IBAN) for the recipient. If BACS data is not provided, an IBAN is required.

Min length: 15
Max length: 34
bacs
object
The account number and sort code of the recipient's account.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
address
object
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
street
required[string]
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters.

Min items: 1
Min length: 1
city
requiredstring
The city where the recipient is located. Maximum of 35 characters.

Min length: 1
Max length: 35
postal_code
requiredstring
The postal code where the recipient is located. Maximum of 16 characters.

Min length: 1
Max length: 16
country
requiredstring
The ISO 3166-1 alpha-2 country code where the recipient is located.

Min length: 2
Max length: 2
Select group for content switcher
Select Language
1// Using BACS, without IBAN or address
2const request: PaymentInitiationRecipientCreateRequest = {
3  name: 'John Doe',
4  bacs: {
5    account: '26207729',
6    sort_code: '560029',
7  },
8};
9try {
10  const response = await plaidClient.paymentInitiationRecipientCreate(request);
11  const recipientID = response.data.recipient_id;
12} catch (error) {
13  // handle error
14}
payment_initiation/recipient/create

Response fields and example

recipient_id
string
A unique ID identifying the recipient
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
3  "request_id": "4zlKapIkTm8p5KM"
4}
Was this helpful?

/payment_initiation/recipient/get

Get payment recipient

Get details about a payment recipient you have previously created.

payment_initiation/recipient/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
recipient_id
requiredstring
The ID of the recipient
Select group for content switcher
Select Language
1const request: PaymentInitiationRecipientGetRequest = {
2  recipient_id: recipientID,
3};
4try {
5  const response = await plaidClient.paymentInitiationRecipientGet(request);
6  const recipientID = response.data.recipient_id;
7  const name = response.data.name;
8  const iban = response.data.iban;
9  const address = response.data.address;
10} catch (error) {
11  // handle error
12}
payment_initiation/recipient/get

Response fields and example

recipient_id
string
The ID of the recipient.
name
string
The name of the recipient.
address
nullableobject
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
street
[string]
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters.

Min items: 1
Min length: 1
city
string
The city where the recipient is located. Maximum of 35 characters.

Min length: 1
Max length: 35
postal_code
string
The postal code where the recipient is located. Maximum of 16 characters.

Min length: 1
Max length: 16
country
string
The ISO 3166-1 alpha-2 country code where the recipient is located.

Min length: 2
Max length: 2
iban
nullablestring
The International Bank Account Number (IBAN) for the recipient.
bacs
nullableobject
The account number and sort code of the recipient's account.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
3  "name": "Wonder Wallet",
4  "iban": "GB29NWBK60161331926819",
5  "address": {
6    "street": [
7      "96 Guild Street",
8      "9th Floor"
9    ],
10    "city": "London",
11    "postal_code": "SE14 8JW",
12    "country": "GB"
13  },
14  "request_id": "4zlKapIkTm8p5KM"
15}
Was this helpful?

/payment_initiation/recipient/list

List payment recipients

The /payment_initiation/recipient/list endpoint list the payment recipients that you have previously created.

payment_initiation/recipient/list

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
Select group for content switcher
Select Language
1try {
2  const response = await plaidClient.paymentInitiationRecipientList({});
3  const recipients = response.data.recipients;
4} catch (error) {
5  // handle error
6}
payment_initiation/recipient/list

Response fields and example

recipients
[object]
An array of payment recipients created for Payment Initiation
recipient_id
string
The ID of the recipient.
name
string
The name of the recipient.
address
nullableobject
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
street
[string]
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters.

Min items: 1
Min length: 1
city
string
The city where the recipient is located. Maximum of 35 characters.

Min length: 1
Max length: 35
postal_code
string
The postal code where the recipient is located. Maximum of 16 characters.

Min length: 1
Max length: 16
country
string
The ISO 3166-1 alpha-2 country code where the recipient is located.

Min length: 2
Max length: 2
iban
nullablestring
The International Bank Account Number (IBAN) for the recipient.
bacs
nullableobject
The account number and sort code of the recipient's account.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "recipients": [
3    {
4      "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
5      "name": "Wonder Wallet",
6      "iban": "GB29NWBK60161331926819",
7      "address": {
8        "street": [
9          "96 Guild Street",
10          "9th Floor"
11        ],
12        "city": "London",
13        "postal_code": "SE14 8JW",
14        "country": "GB"
15      }
16    }
17  ],
18  "request_id": "4zlKapIkTm8p5KM"
19}
Was this helpful?

/payment_initiation/payment/create

Create a payment

After creating a payment recipient, you can use the /payment_initiation/payment/create endpoint to create a payment to that recipient. Payments can be one-time or standing order (recurring) and can be denominated in either EUR, GBP or other chosen currency. If making domestic GBP-denominated payments, your recipient must have been created with BACS numbers. In general, EUR-denominated payments will be sent via SEPA Credit Transfer, GBP-denominated payments will be sent via the Faster Payments network and for non-Eurozone markets typically via the local payment scheme, but the payment network used will be determined by the institution. Payments sent via Faster Payments will typically arrive immediately, while payments sent via SEPA Credit Transfer or other local payment schemes will typically arrive in one business day.
Standing orders (recurring payments) must be denominated in GBP and can only be sent to recipients in the UK. Once created, standing order payments cannot be modified or canceled via the API. An end user can cancel or modify a standing order directly on their banking application or website, or by contacting the bank. Standing orders will follow the payment rules of the underlying rails (Faster Payments in UK). Payments can be sent Monday to Friday, excluding bank holidays. If the pre-arranged date falls on a weekend or bank holiday, the payment is made on the next working day. It is not possible to guarantee the exact time the payment will reach the recipient’s account, although at least 90% of standing order payments are sent by 6am.
In the Development environment, payments must be below 5 GBP or other chosen currency. For details on any payment limits in Production, contact your Plaid Account Manager.

payment_initiation/payment/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
recipient_id
requiredstring
The ID of the recipient the payment is for.
reference
requiredstring
A reference for the payment. This must be an alphanumeric string with at most 18 characters and must not contain any special characters (since not all institutions support them). In order to track settlement via Payment Confirmation, each payment must have a unique reference. If the reference provided through the API is not unique, Plaid will adjust it. Both the originally provided and automatically adjusted references (if any) can be found in the reference and adjusted_reference fields, respectively.

Min length: 1
Max length: 18
amount
requiredobject
The amount and currency of a payment
currency
requiredstring
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
requirednumber
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1.

Format: double
schedule
object
The schedule that the payment will be executed on. If a schedule is provided, the payment is automatically set up as a standing order. If no schedule is specified, the payment will be executed only once.
interval
requiredstring
The frequency interval of the payment.

Possible values: WEEKLY, MONTHLY
Min length: 1
interval_execution_day
requiredinteger
The day of the interval on which to schedule the payment.
If the payment interval is weekly, interval_execution_day should be an integer from 1 (Monday) to 7 (Sunday).
If the payment interval is monthly, interval_execution_day should be an integer indicating which day of the month to make the payment on. Integers from 1 to 28 can be used to make a payment on that day of the month. Negative integers from -1 to -5 can be used to make a payment relative to the end of the month. To make a payment on the last day of the month, use -1; to make the payment on the second-to-last day, use -2, and so on.
start_date
requiredstring
A date in ISO 8601 format (YYYY-MM-DD). Standing order payments will begin on the first interval_execution_day on or after the start_date.
If the first interval_execution_day on or after the start date is also the same day that /payment_initiation/payment/create was called, the bank may make the first payment on that day, but it is not guaranteed to do so.

Format: date
end_date
string
A date in ISO 8601 format (YYYY-MM-DD). Standing order payments will end on the last interval_execution_day on or before the end_date. If the only interval_execution_day between the start date and the end date (inclusive) is also the same day that /payment_initiation/payment/create was called, the bank may make a payment on that day, but it is not guaranteed to do so.

Format: date
adjusted_start_date
string
The start date sent to the bank after adjusting for holidays or weekends. Will be provided in ISO 8601 format (YYYY-MM-DD). If the start date did not require adjustment, this field will be null.

Format: date
options
object
Additional payment options
request_refund_details
boolean
When true, Plaid will attempt to request refund details from the payee's financial institution. Support varies between financial institutions and will not always be available. If refund details could be retrieved, they will be available in the /payment_initiation/payment/get response.
iban
string
The International Bank Account Number (IBAN) for the payer's account. Where possible, the end user will be able to send payments only from the specified bank account if provided.

Min length: 15
Max length: 34
bacs
object
An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
scheme
string
Payment scheme. If not specified - the default in the region will be used (e.g. SEPA_CREDIT_TRANSFER for EU). Using unsupported values will result in a failed payment.
LOCAL_DEFAULT: The default payment scheme for the selected market and currency will be used.
LOCAL_INSTANT: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. If the market does not support an Instant Scheme (e.g. Denmark), the default in the region will be used.
SEPA_CREDIT_TRANSFER: The standard payment to a beneficiary within the SEPA area.
SEPA_CREDIT_TRANSFER_INSTANT: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks.

Possible values: null, LOCAL_DEFAULT, LOCAL_INSTANT, SEPA_CREDIT_TRANSFER, SEPA_CREDIT_TRANSFER_INSTANT
Select group for content switcher
Select Language
1const request: PaymentInitiationPaymentCreateRequest = {
2  recipient_id: recipientID,
3  reference: 'TestPayment',
4  amount: {
5    currency: 'GBP',
6    value: 100.0,
7  },
8};
9try {
10  const response = await plaidClient.paymentInitiationPaymentCreate(request);
11  const paymentID = response.data.payment_id;
12  const status = response.data.status;
13} catch (error) {
14  // handle error
15}
payment_initiation/payment/create

Response fields and example

payment_id
string
A unique ID identifying the payment
status
string
For a payment returned by this endpoint, there is only one possible value:
PAYMENT_STATUS_INPUT_NEEDED: The initial phase of the payment

Possible values: PAYMENT_STATUS_INPUT_NEEDED
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
3  "status": "PAYMENT_STATUS_INPUT_NEEDED",
4  "request_id": "4ciYVmesrySiUAB"
5}
Was this helpful?

/payment_initiation/payment/get

Get payment details

The /payment_initiation/payment/get endpoint can be used to check the status of a payment, as well as to receive basic information such as recipient and payment amount. In the case of standing orders, the /payment_initiation/payment/get endpoint will provide information about the status of the overall standing order itself; the API cannot be used to retrieve payment status for individual payments within a standing order.

payment_initiation/payment/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
payment_id
requiredstring
The payment_id returned from /payment_initiation/payment/create.
Select group for content switcher
Select Language
1const request: PaymentInitiationPaymentGetRequest = {
2  payment_id: paymentID,
3};
4try {
5  const response = await plaidClient.paymentInitiationPaymentGet(request);
6  const paymentID = response.data.payment_id;
7  const paymentToken = response.data.payment_token;
8  const reference = response.data.reference;
9  const amount = response.data.amount;
10  const status = response.data.status;
11  const lastStatusUpdate = response.data.last_status_update;
12  const paymentTokenExpirationTime =
13    response.data.payment_token_expiration_time;
14  const recipientID = response.data.recipient_id;
15} catch (error) {
16  // handle error
17}
payment_initiation/payment/get

Response fields and example

payment_id
string
The ID of the payment. Like all Plaid identifiers, the payment_id is case sensitive.
amount
object
The amount and currency of a payment
currency
string
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
number
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1.

Format: double
status
string
The status of the payment.
PAYMENT_STATUS_INPUT_NEEDED: This is the initial state of all payments. It indicates that the payment is waiting on user input to continue processing. A payment may re-enter this state later on if further input is needed.
PAYMENT_STATUS_INITIATED: The payment has been successfully authorised and accepted by the financial institution. For successful payments, this is a potential terminal status. Further status transitions can be to REJECTED and, when supported by the institution, to EXECUTED.
PAYMENT_STATUS_INSUFFICIENT_FUNDS: The payment has failed due to insufficient funds.
PAYMENT_STATUS_FAILED: The payment has failed to be initiated. This error may be caused by transient system outages and is retryable once the root cause is resolved.
PAYMENT_STATUS_BLOCKED: The payment has been blocked by Plaid. This can occur, for example, due to Plaid flagging the payment as potentially risky. This is a retryable error.
PAYMENT_STATUS_AUTHORISING: The payment is currently being processed. The payment will automatically exit this state when the financial institution has authorised the transaction.
PAYMENT_STATUS_CANCELLED: The payment was cancelled (typically by the end user) during authorisation.
PAYMENT_STATUS_EXECUTED: The funds have successfully left the payer account and payment is considered complete. Not all institutions support this status: support is more common in the UK, and less common in the EU. For institutions where this status is not supported, the terminal status for a successful payment will be PAYMENT_STATUS_INITIATED.
PAYMENT_STATUS_SETTLED: The payment has settled and funds are available for use. A payment will typically settle within seconds to several days, depending on which payment rail is used. This status is only available to customers using Plaid Virtual Accounts.
PAYMENT_STATUS_ESTABLISHED: Indicates that the standing order has been successfully established. This state is only used for standing orders.
PAYMENT_STATUS_REJECTED: The payment was rejected by the financial institution.
Deprecated: These statuses will be removed in a future release.
PAYMENT_STATUS_UNKNOWN: The payment status is unknown.
PAYMENT_STATUS_PROCESSING: The payment is currently being processed. The payment will automatically exit this state when processing is complete.
PAYMENT_STATUS_COMPLETED: Indicates that the standing order has been successfully established. This state is only used for standing orders.

Possible values: PAYMENT_STATUS_INPUT_NEEDED, PAYMENT_STATUS_PROCESSING, PAYMENT_STATUS_INITIATED, PAYMENT_STATUS_COMPLETED, PAYMENT_STATUS_INSUFFICIENT_FUNDS, PAYMENT_STATUS_FAILED, PAYMENT_STATUS_BLOCKED, PAYMENT_STATUS_UNKNOWN, PAYMENT_STATUS_EXECUTED, PAYMENT_STATUS_SETTLED, PAYMENT_STATUS_AUTHORISING, PAYMENT_STATUS_CANCELLED, PAYMENT_STATUS_ESTABLISHED, PAYMENT_STATUS_REJECTED
recipient_id
string
The ID of the recipient
reference
string
A reference for the payment.
adjusted_reference
nullablestring
The value of the reference sent to the bank after adjustment to pass bank validation rules.
last_status_update
string
The date and time of the last time the status was updated, in IS0 8601 format

Format: date-time
schedule
nullableobject
The schedule that the payment will be executed on. If a schedule is provided, the payment is automatically set up as a standing order. If no schedule is specified, the payment will be executed only once.
interval
string
The frequency interval of the payment.

Possible values: WEEKLY, MONTHLY
Min length: 1
interval_execution_day
integer
The day of the interval on which to schedule the payment.
If the payment interval is weekly, interval_execution_day should be an integer from 1 (Monday) to 7 (Sunday).
If the payment interval is monthly, interval_execution_day should be an integer indicating which day of the month to make the payment on. Integers from 1 to 28 can be used to make a payment on that day of the month. Negative integers from -1 to -5 can be used to make a payment relative to the end of the month. To make a payment on the last day of the month, use -1; to make the payment on the second-to-last day, use -2, and so on.
start_date
string
A date in ISO 8601 format (YYYY-MM-DD). Standing order payments will begin on the first interval_execution_day on or after the start_date.
If the first interval_execution_day on or after the start date is also the same day that /payment_initiation/payment/create was called, the bank may make the first payment on that day, but it is not guaranteed to do so.

Format: date
end_date
nullablestring
A date in ISO 8601 format (YYYY-MM-DD). Standing order payments will end on the last interval_execution_day on or before the end_date. If the only interval_execution_day between the start date and the end date (inclusive) is also the same day that /payment_initiation/payment/create was called, the bank may make a payment on that day, but it is not guaranteed to do so.

Format: date
adjusted_start_date
nullablestring
The start date sent to the bank after adjusting for holidays or weekends. Will be provided in ISO 8601 format (YYYY-MM-DD). If the start date did not require adjustment, this field will be null.

Format: date
refund_details
nullableobject
Details about external payment refund
name
string
The name of the account holder.
iban
nullablestring
The International Bank Account Number (IBAN) for the account.
bacs
nullableobject
The account number and sort code of the recipient's account.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
bacs
nullableobject
The account number and sort code of the sender's account, if specified in the /payment_initiation/payment/create call.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
iban
nullablestring
The International Bank Account Number (IBAN) for the sender, if specified in the /payment_initiation/payment/create call.
refund_ids
nullable[string]
Refund IDs associated with the payment.
amount_refunded
nullableobject
The amount that has been refunded already. Subtract this from the payment amount to calculate the amount still available to refund.
currency
string
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
number
The amount of the payment. Must contain at most two digits of precision e.g. 1.23.

Format: double
Minimum: 0.01
wallet_id
nullablestring
The EMI (E-Money Institution) wallet that this payment is associated with, if any. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests.
scheme
nullablestring
Payment scheme. If not specified - the default in the region will be used (e.g. SEPA_CREDIT_TRANSFER for EU). Using unsupported values will result in a failed payment.
LOCAL_DEFAULT: The default payment scheme for the selected market and currency will be used.
LOCAL_INSTANT: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. If the market does not support an Instant Scheme (e.g. Denmark), the default in the region will be used.
SEPA_CREDIT_TRANSFER: The standard payment to a beneficiary within the SEPA area.
SEPA_CREDIT_TRANSFER_INSTANT: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks.

Possible values: null, LOCAL_DEFAULT, LOCAL_INSTANT, SEPA_CREDIT_TRANSFER, SEPA_CREDIT_TRANSFER_INSTANT
adjusted_scheme
nullablestring
Payment scheme. If not specified - the default in the region will be used (e.g. SEPA_CREDIT_TRANSFER for EU). Using unsupported values will result in a failed payment.
LOCAL_DEFAULT: The default payment scheme for the selected market and currency will be used.
LOCAL_INSTANT: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. If the market does not support an Instant Scheme (e.g. Denmark), the default in the region will be used.
SEPA_CREDIT_TRANSFER: The standard payment to a beneficiary within the SEPA area.
SEPA_CREDIT_TRANSFER_INSTANT: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks.

Possible values: null, LOCAL_DEFAULT, LOCAL_INSTANT, SEPA_CREDIT_TRANSFER, SEPA_CREDIT_TRANSFER_INSTANT
consent_id
nullablestring
The payment consent ID that this payment was initiated with. Is present only when payment was initiated using the payment consent.
transaction_id
nullablestring
The transaction ID that this payment is associated with, if any. This is present only when a payment was initiated using virtual accounts.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
3  "payment_token": "payment-token-sandbox-c6a26505-42b4-46fe-8ecf-bf9edcafbebb",
4  "reference": "Account Funding 99744",
5  "amount": {
6    "currency": "GBP",
7    "value": 100
8  },
9  "status": "PAYMENT_STATUS_INPUT_NEEDED",
10  "last_status_update": "2019-11-06T21:10:52Z",
11  "payment_expiration_time": "2019-11-06T21:25:52Z",
12  "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
13  "bacs": {
14    "account": "31926819",
15    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
16    "sort_code": "601613"
17  },
18  "iban": null,
19  "request_id": "aEAQmewMzlVa1k6"
20}
Was this helpful?

/payment_initiation/payment/list

List payments

The /payment_initiation/payment/list endpoint can be used to retrieve all created payments. By default, the 10 most recent payments are returned. You can request more payments and paginate through the results using the optional count and cursor parameters.

payment_initiation/payment/list

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
count
integer
The maximum number of payments to return. If count is not specified, a maximum of 10 payments will be returned, beginning with the most recent payment before the cursor (if specified).

Minimum: 1
Maximum: 200
Default: 10
cursor
string
A string in RFC 3339 format (i.e. "2019-12-06T22:35:49Z"). Only payments created before the cursor will be returned.

Format: date-time
consent_id
string
The consent ID. If specified, only payments, executed using this consent, will be returned.
Select group for content switcher
Select Language
1const request: PaymentInitiationPaymentListRequest = {
2  count: 10,
3  cursor: '2019-12-06T22:35:49Z',
4};
5try {
6  const response = await plaidClient.paymentInitiationPaymentList(request);
7  const payments = response.data.payments;
8  const nextCursor = response.data.next_cursor;
9} catch (error) {
10  // handle error
11}
payment_initiation/payment/list

Response fields and example

payments
[object]
An array of payments that have been created, associated with the given client_id.
payment_id
string
The ID of the payment. Like all Plaid identifiers, the payment_id is case sensitive.
amount
object
The amount and currency of a payment
currency
string
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
number
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1.

Format: double
status
string
The status of the payment.
PAYMENT_STATUS_INPUT_NEEDED: This is the initial state of all payments. It indicates that the payment is waiting on user input to continue processing. A payment may re-enter this state later on if further input is needed.
PAYMENT_STATUS_INITIATED: The payment has been successfully authorised and accepted by the financial institution. For successful payments, this is a potential terminal status. Further status transitions can be to REJECTED and, when supported by the institution, to EXECUTED.
PAYMENT_STATUS_INSUFFICIENT_FUNDS: The payment has failed due to insufficient funds.
PAYMENT_STATUS_FAILED: The payment has failed to be initiated. This error may be caused by transient system outages and is retryable once the root cause is resolved.
PAYMENT_STATUS_BLOCKED: The payment has been blocked by Plaid. This can occur, for example, due to Plaid flagging the payment as potentially risky. This is a retryable error.
PAYMENT_STATUS_AUTHORISING: The payment is currently being processed. The payment will automatically exit this state when the financial institution has authorised the transaction.
PAYMENT_STATUS_CANCELLED: The payment was cancelled (typically by the end user) during authorisation.
PAYMENT_STATUS_EXECUTED: The funds have successfully left the payer account and payment is considered complete. Not all institutions support this status: support is more common in the UK, and less common in the EU. For institutions where this status is not supported, the terminal status for a successful payment will be PAYMENT_STATUS_INITIATED.
PAYMENT_STATUS_SETTLED: The payment has settled and funds are available for use. A payment will typically settle within seconds to several days, depending on which payment rail is used. This status is only available to customers using Plaid Virtual Accounts.
PAYMENT_STATUS_ESTABLISHED: Indicates that the standing order has been successfully established. This state is only used for standing orders.
PAYMENT_STATUS_REJECTED: The payment was rejected by the financial institution.
Deprecated: These statuses will be removed in a future release.
PAYMENT_STATUS_UNKNOWN: The payment status is unknown.
PAYMENT_STATUS_PROCESSING: The payment is currently being processed. The payment will automatically exit this state when processing is complete.
PAYMENT_STATUS_COMPLETED: Indicates that the standing order has been successfully established. This state is only used for standing orders.

Possible values: PAYMENT_STATUS_INPUT_NEEDED, PAYMENT_STATUS_PROCESSING, PAYMENT_STATUS_INITIATED, PAYMENT_STATUS_COMPLETED, PAYMENT_STATUS_INSUFFICIENT_FUNDS, PAYMENT_STATUS_FAILED, PAYMENT_STATUS_BLOCKED, PAYMENT_STATUS_UNKNOWN, PAYMENT_STATUS_EXECUTED, PAYMENT_STATUS_SETTLED, PAYMENT_STATUS_AUTHORISING, PAYMENT_STATUS_CANCELLED, PAYMENT_STATUS_ESTABLISHED, PAYMENT_STATUS_REJECTED
recipient_id
string
The ID of the recipient
reference
string
A reference for the payment.
adjusted_reference
nullablestring
The value of the reference sent to the bank after adjustment to pass bank validation rules.
last_status_update
string
The date and time of the last time the status was updated, in IS0 8601 format

Format: date-time
schedule
nullableobject
The schedule that the payment will be executed on. If a schedule is provided, the payment is automatically set up as a standing order. If no schedule is specified, the payment will be executed only once.
interval
string
The frequency interval of the payment.

Possible values: WEEKLY, MONTHLY
Min length: 1
interval_execution_day
integer
The day of the interval on which to schedule the payment.
If the payment interval is weekly, interval_execution_day should be an integer from 1 (Monday) to 7 (Sunday).
If the payment interval is monthly, interval_execution_day should be an integer indicating which day of the month to make the payment on. Integers from 1 to 28 can be used to make a payment on that day of the month. Negative integers from -1 to -5 can be used to make a payment relative to the end of the month. To make a payment on the last day of the month, use -1; to make the payment on the second-to-last day, use -2, and so on.
start_date
string
A date in ISO 8601 format (YYYY-MM-DD). Standing order payments will begin on the first interval_execution_day on or after the start_date.
If the first interval_execution_day on or after the start date is also the same day that /payment_initiation/payment/create was called, the bank may make the first payment on that day, but it is not guaranteed to do so.

Format: date
end_date
nullablestring
A date in ISO 8601 format (YYYY-MM-DD). Standing order payments will end on the last interval_execution_day on or before the end_date. If the only interval_execution_day between the start date and the end date (inclusive) is also the same day that /payment_initiation/payment/create was called, the bank may make a payment on that day, but it is not guaranteed to do so.

Format: date
adjusted_start_date
nullablestring
The start date sent to the bank after adjusting for holidays or weekends. Will be provided in ISO 8601 format (YYYY-MM-DD). If the start date did not require adjustment, this field will be null.

Format: date
refund_details
nullableobject
Details about external payment refund
name
string
The name of the account holder.
iban
nullablestring
The International Bank Account Number (IBAN) for the account.
bacs
nullableobject
The account number and sort code of the recipient's account.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
bacs
nullableobject
The account number and sort code of the sender's account, if specified in the /payment_initiation/payment/create call.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
iban
nullablestring
The International Bank Account Number (IBAN) for the sender, if specified in the /payment_initiation/payment/create call.
refund_ids
nullable[string]
Refund IDs associated with the payment.
amount_refunded
nullableobject
The amount that has been refunded already. Subtract this from the payment amount to calculate the amount still available to refund.
currency
string
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
number
The amount of the payment. Must contain at most two digits of precision e.g. 1.23.

Format: double
Minimum: 0.01
wallet_id
nullablestring
The EMI (E-Money Institution) wallet that this payment is associated with, if any. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests.
scheme
nullablestring
Payment scheme. If not specified - the default in the region will be used (e.g. SEPA_CREDIT_TRANSFER for EU). Using unsupported values will result in a failed payment.
LOCAL_DEFAULT: The default payment scheme for the selected market and currency will be used.
LOCAL_INSTANT: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. If the market does not support an Instant Scheme (e.g. Denmark), the default in the region will be used.
SEPA_CREDIT_TRANSFER: The standard payment to a beneficiary within the SEPA area.
SEPA_CREDIT_TRANSFER_INSTANT: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks.

Possible values: null, LOCAL_DEFAULT, LOCAL_INSTANT, SEPA_CREDIT_TRANSFER, SEPA_CREDIT_TRANSFER_INSTANT
adjusted_scheme
nullablestring
Payment scheme. If not specified - the default in the region will be used (e.g. SEPA_CREDIT_TRANSFER for EU). Using unsupported values will result in a failed payment.
LOCAL_DEFAULT: The default payment scheme for the selected market and currency will be used.
LOCAL_INSTANT: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. If the market does not support an Instant Scheme (e.g. Denmark), the default in the region will be used.
SEPA_CREDIT_TRANSFER: The standard payment to a beneficiary within the SEPA area.
SEPA_CREDIT_TRANSFER_INSTANT: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks.

Possible values: null, LOCAL_DEFAULT, LOCAL_INSTANT, SEPA_CREDIT_TRANSFER, SEPA_CREDIT_TRANSFER_INSTANT
consent_id
nullablestring
The payment consent ID that this payment was initiated with. Is present only when payment was initiated using the payment consent.
transaction_id
nullablestring
The transaction ID that this payment is associated with, if any. This is present only when a payment was initiated using virtual accounts.
next_cursor
nullablestring
The value that, when used as the optional cursor parameter to /payment_initiation/payment/list, will return the next unreturned payment as its first payment.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "payments": [
3    {
4      "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
5      "reference": "Account Funding 99744",
6      "amount": {
7        "currency": "GBP",
8        "value": 100
9      },
10      "status": "PAYMENT_STATUS_INPUT_NEEDED",
11      "last_status_update": "2019-11-06T21:10:52Z",
12      "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
13      "bacs": {
14        "account": "31926819",
15        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
16        "sort_code": "601613"
17      },
18      "iban": null
19    }
20  ],
21  "next_cursor": "2020-01-01T00:00:00Z",
22  "request_id": "aEAQmewMzlVa1k6"
23}
Was this helpful?

/payment_initiation/payment/reverse

Reverse an existing payment

Reverse a settled payment from a Plaid virtual account.
The original payment must be in a settled state to be refunded. To refund partially, specify the amount as part of the request. If the amount is not specified, the refund amount will be equal to all of the remaining payment amount that has not been refunded yet.
The refund will go back to the source account that initiated the payment. The original payment must have been initiated to a Plaid virtual account so that this account can be used to initiate the refund.

payment_initiation/payment/reverse

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
payment_id
requiredstring
The ID of the payment to reverse
idempotency_key
requiredstring
A random key provided by the client, per unique wallet transaction. Maximum of 128 characters.
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. If a request to execute a wallet transaction fails due to a network connection error, then after a minimum delay of one minute, you can retry the request with the same idempotency key to guarantee that only a single wallet transaction is created. If the request was successfully processed, it will prevent any transaction that uses the same idempotency key, and was received within 24 hours of the first request, from being processed.

Max length: 128
Min length: 1
reference
requiredstring
A reference for the refund. This must be an alphanumeric string with 6 to 18 characters and must not contain any special characters or spaces.

Max length: 18
Min length: 6
amount
object
An amount to refund the payment partially. If this amount is not specified, the payment is refunded fully for the remaining amount.
currency
requiredstring
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
requirednumber
The amount of the payment. Must contain at most two digits of precision e.g. 1.23.

Format: double
Minimum: 0.01
Select Language
1const request: PaymentInitiationPaymentReverseRequest = {
2  payment_id: paymentID,
3  reference: 'Refund for purchase ABC123',
4  idempotency_key: 'ae009325-df8d-4f52-b1e0-53ff26c23912',
5};
6try {
7  const response = await plaidClient.paymentInitiationPaymentReverse(request);
8  const refundID = response.data.refund_id;
9  const status = response.data.status;
10} catch (error) {
11  // handle error
12}
payment_initiation/payment/reverse

Response fields and example

refund_id
string
A unique ID identifying the refund
status
string
The status of the transaction.
AUTHORISING: The transaction is being processed for validation and compliance.
INITIATED: The transaction has been initiated and is currently being processed.
EXECUTED: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions.
SETTLED: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used.
FAILED: The transaction failed to process successfully. This is a terminal status.
BLOCKED: The transaction has been blocked for violating compliance rules. This is a terminal status.

Possible values: AUTHORISING, INITIATED, EXECUTED, SETTLED, BLOCKED, FAILED
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "refund_id": "wallet-transaction-id-production-c5f8cd31-6cae-4cad-9b0d-f7c10be9cc4b",
3  "request_id": "HtlKzBX0fMeF7mU",
4  "status": "INITIATED"
5}
Was this helpful?

/payment_initiation/consent/create

Create payment consent

The /payment_initiation/consent/create endpoint is used to create a payment consent, which can be used to initiate payments on behalf of the user. Payment consents are created with UNAUTHORISED status by default and must be authorised by the user before payments can be initiated.
Consents can be limited in time and scope, and have constraints that describe limitations for payments.

payment_initiation/consent/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
recipient_id
requiredstring
The ID of the recipient the payment consent is for. The created consent can be used to transfer funds to this recipient only.
reference
requiredstring
A reference for the payment consent. This must be an alphanumeric string with at most 18 characters and must not contain any special characters.

Min length: 1
Max length: 18
scopes
required[string]
An array of payment consent scopes.

Min items: 1
Possible values: ME_TO_ME, EXTERNAL
constraints
requiredobject
Limitations that will be applied to payments initiated using the payment consent.
valid_date_time
object
Life span for the payment consent. After the to date the payment consent expires and can no longer be used for payment initiation.
from
string
The date and time from which the consent should be active, in ISO 8601 format.

Format: date-time
to
string
The date and time at which the consent expires, in ISO 8601 format.

Format: date-time
max_payment_amount
requiredobject
The amount and currency of a payment
currency
requiredstring
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
requirednumber
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1.

Format: double
periodic_amounts
required[object]
A list of amount limitations per period of time.

Min items: 1
amount
requiredobject
The amount and currency of a payment
currency
requiredstring
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
requirednumber
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1.

Format: double
interval
requiredstring
Payment consent periodic interval.

Possible values: DAY, WEEK, MONTH, YEAR
alignment
requiredstring
Where the payment consent period should start.
CALENDAR: line up with a calendar.
CONSENT: on the date of consent creation.

Possible values: CALENDAR, CONSENT
options
object
Additional payment consent options
request_refund_details
boolean
When true, Plaid will attempt to request refund details from the payee's financial institution. Support varies between financial institutions and will not always be available. If refund details could be retrieved, they will be available in the /payment_initiation/payment/get response.
iban
string
The International Bank Account Number (IBAN) for the payer's account. Where possible, the end user will be able to set up payment consent using only the specified bank account if provided.

Min length: 15
Max length: 34
bacs
object
An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
Select Language
1const request: PaymentInitiationConsentCreateRequest = {
2  recipient_id: recipientID,
3  reference: 'TestPaymentConsent',
4  scopes: new Set([PaymentInitiationConsentScope.MeToMe]),
5  constraints: {
6    valid_date_time: {
7      to: '2024-12-31T23:59:59Z',
8    },
9    max_payment_amount: {
10      currency: PaymentAmountCurrency.Gbp,
11      value: 15,
12    },
13    periodic_amounts: [
14      {
15        amount: {
16          currency: PaymentAmountCurrency.Gbp,
17          value: 40,
18        },
19        alignment: PaymentConsentPeriodicAlignment.Calendar,
20        interval: PaymentConsentPeriodicInterval.Month,
21      },
22    ],
23  },
24};
25
26try {
27  const response = await plaidClient.paymentInitiationConsentCreate(request);
28  const consentID = response.data.consent_id;
29  const status = response.data.status;
30} catch (error) {
31  // handle error
32}
payment_initiation/consent/create

Response fields and example

consent_id
string
A unique ID identifying the payment consent.
status
string
The status of the payment consent.
UNAUTHORISED: Consent created, but requires user authorisation.
REJECTED: Consent authorisation was rejected by the user and/or the bank.
AUTHORISED: Consent is active and ready to be used.
REVOKED: Consent has been revoked and can no longer be used.
EXPIRED: Consent is no longer valid.

Possible values: UNAUTHORISED, AUTHORISED, REVOKED, REJECTED, EXPIRED
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "consent_id": "consent-id-production-feca8a7a-5491-4444-9999-f3062bb735d3",
3  "status": "UNAUTHORISED",
4  "request_id": "4ciYmmesdqSiUAB"
5}
Was this helpful?

/payment_initiation/consent/get

Get payment consent

The /payment_initiation/consent/get endpoint can be used to check the status of a payment consent, as well as to receive basic information such as recipient and constraints.

payment_initiation/consent/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
consent_id
requiredstring
The consent_id returned from /payment_initiation/consent/create.
Select Language
1const request: PaymentInitiationConsentGetRequest = {
2  consent_id: consentID,
3};
4
5try {
6  const response = await plaidClient.paymentInitiationConsentGet(request);
7  const consentID = response.data.consent_id;
8  const status = response.data.status;
9} catch (error) {
10  // handle error
11}
payment_initiation/consent/get

Response fields and example

consent_id
string
The consent ID.

Min length: 1
status
string
The status of the payment consent.
UNAUTHORISED: Consent created, but requires user authorisation.
REJECTED: Consent authorisation was rejected by the user and/or the bank.
AUTHORISED: Consent is active and ready to be used.
REVOKED: Consent has been revoked and can no longer be used.
EXPIRED: Consent is no longer valid.

Possible values: UNAUTHORISED, AUTHORISED, REVOKED, REJECTED, EXPIRED
created_at
string
Consent creation timestamp, in ISO 8601 format.

Format: date-time
recipient_id
string
The ID of the recipient the payment consent is for.

Min length: 1
reference
string
A reference for the payment consent.
constraints
object
Limitations that will be applied to payments initiated using the payment consent.
valid_date_time
nullableobject
Life span for the payment consent. After the to date the payment consent expires and can no longer be used for payment initiation.
from
nullablestring
The date and time from which the consent should be active, in ISO 8601 format.

Format: date-time
to
nullablestring
The date and time at which the consent expires, in ISO 8601 format.

Format: date-time
max_payment_amount
object
The amount and currency of a payment
currency
string
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
number
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1.

Format: double
periodic_amounts
[object]
A list of amount limitations per period of time.

Min items: 1
amount
object
The amount and currency of a payment
currency
string
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
number
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1.

Format: double
interval
string
Payment consent periodic interval.

Possible values: DAY, WEEK, MONTH, YEAR
alignment
string
Where the payment consent period should start.
CALENDAR: line up with a calendar.
CONSENT: on the date of consent creation.

Possible values: CALENDAR, CONSENT
scopes
[string]
An array of payment consent scopes.

Possible values: ME_TO_ME, EXTERNAL
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "4ciYuuesdqSiUAB",
3  "consent_id": "consent-id-production-feca8a7a-5491-4aef-9298-f3062bb735d3",
4  "status": "AUTHORISED",
5  "created_at": "2021-10-30T15:26:48Z",
6  "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f6",
7  "reference": "ref-00001",
8  "constraints": {
9    "valid_date_time": {
10      "from": "2021-12-25T11:12:13Z",
11      "to": "2022-12-31T15:26:48Z"
12    },
13    "max_payment_amount": {
14      "currency": "GBP",
15      "value": 100
16    },
17    "periodic_amounts": [
18      {
19        "amount": {
20          "currency": "GBP",
21          "value": 300
22        },
23        "interval": "WEEK",
24        "alignment": "CALENDAR"
25      }
26    ]
27  },
28  "scopes": [
29    "ME_TO_ME"
30  ]
31}
Was this helpful?

/payment_initiation/consent/revoke

Revoke payment consent

The /payment_initiation/consent/revoke endpoint can be used to revoke the payment consent. Once the consent is revoked, it is not possible to initiate payments using it.

payment_initiation/consent/revoke

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
consent_id
requiredstring
The consent ID.
Select Language
1const request: PaymentInitiationConsentRevokeRequest = {
2  consent_id: consentID,
3};
4try {
5  const response = await plaidClient.paymentInitiationConsentRevoke(request);
6} catch (error) {
7  // handle error
8}
payment_initiation/consent/revoke

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "4ciYaaesdqSiUAB"
3}
Was this helpful?

/payment_initiation/consent/payment/execute

Execute a single payment using consent

The /payment_initiation/consent/payment/execute endpoint can be used to execute payments using payment consent.

payment_initiation/consent/payment/execute

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
consent_id
requiredstring
The consent ID.
amount
requiredobject
The amount and currency of a payment
currency
requiredstring
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
requirednumber
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1.

Format: double
idempotency_key
requiredstring
A random key provided by the client, per unique consent payment. Maximum of 128 characters.
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. If a request to execute a consent payment fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single payment is created. If the request was successfully processed, it will prevent any payment that uses the same idempotency key, and was received within 24 hours of the first request, from being processed.

Max length: 128
Min length: 1
Select Language
1const request: PaymentInitiationConsentPaymentExecuteRequest = {
2  consent_id: consentID,
3  amount: {
4    currency: PaymentAmountCurrency.Gbp,
5    value: 7.99,
6  },
7  idempotency_key: idempotencyKey,
8};
9try {
10  const response = await plaidClient.paymentInitiationConsentPaymentExecute(
11    request,
12  );
13  const paymentID = response.data.payment_id;
14  const status = response.data.status;
15} catch (error) {
16  // handle error
17}
payment_initiation/consent/payment/execute

Response fields and example

payment_id
string
A unique ID identifying the payment
status
string
The status of the payment.
PAYMENT_STATUS_INPUT_NEEDED: This is the initial state of all payments. It indicates that the payment is waiting on user input to continue processing. A payment may re-enter this state later on if further input is needed.
PAYMENT_STATUS_INITIATED: The payment has been successfully authorised and accepted by the financial institution. For successful payments, this is a potential terminal status. Further status transitions can be to REJECTED and, when supported by the institution, to EXECUTED.
PAYMENT_STATUS_INSUFFICIENT_FUNDS: The payment has failed due to insufficient funds.
PAYMENT_STATUS_FAILED: The payment has failed to be initiated. This error may be caused by transient system outages and is retryable once the root cause is resolved.
PAYMENT_STATUS_BLOCKED: The payment has been blocked by Plaid. This can occur, for example, due to Plaid flagging the payment as potentially risky. This is a retryable error.
PAYMENT_STATUS_AUTHORISING: The payment is currently being processed. The payment will automatically exit this state when the financial institution has authorised the transaction.
PAYMENT_STATUS_CANCELLED: The payment was cancelled (typically by the end user) during authorisation.
PAYMENT_STATUS_EXECUTED: The funds have successfully left the payer account and payment is considered complete. Not all institutions support this status: support is more common in the UK, and less common in the EU. For institutions where this status is not supported, the terminal status for a successful payment will be PAYMENT_STATUS_INITIATED.
PAYMENT_STATUS_SETTLED: The payment has settled and funds are available for use. A payment will typically settle within seconds to several days, depending on which payment rail is used. This status is only available to customers using Plaid Virtual Accounts.
PAYMENT_STATUS_ESTABLISHED: Indicates that the standing order has been successfully established. This state is only used for standing orders.
PAYMENT_STATUS_REJECTED: The payment was rejected by the financial institution.
Deprecated: These statuses will be removed in a future release.
PAYMENT_STATUS_UNKNOWN: The payment status is unknown.
PAYMENT_STATUS_PROCESSING: The payment is currently being processed. The payment will automatically exit this state when processing is complete.
PAYMENT_STATUS_COMPLETED: Indicates that the standing order has been successfully established. This state is only used for standing orders.

Possible values: PAYMENT_STATUS_INPUT_NEEDED, PAYMENT_STATUS_PROCESSING, PAYMENT_STATUS_INITIATED, PAYMENT_STATUS_COMPLETED, PAYMENT_STATUS_INSUFFICIENT_FUNDS, PAYMENT_STATUS_FAILED, PAYMENT_STATUS_BLOCKED, PAYMENT_STATUS_UNKNOWN, PAYMENT_STATUS_EXECUTED, PAYMENT_STATUS_SETTLED, PAYMENT_STATUS_AUTHORISING, PAYMENT_STATUS_CANCELLED, PAYMENT_STATUS_ESTABLISHED, PAYMENT_STATUS_REJECTED
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
3  "request_id": "4ciYccesdqSiUAB",
4  "status": "PAYMENT_STATUS_INITIATED"
5}
Was this helpful?

Webhooks

Updates are sent to indicate that the status of an initiated payment has changed. All Payment Initiation webhooks have a webhook_type of PAYMENT_INITIATION.

PAYMENT_STATUS_UPDATE

Fired when the status of a payment has changed.

webhook_type
string
PAYMENT_INITIATION
webhook_code
string
PAYMENT_STATUS_UPDATE
payment_id
string
The payment_id for the payment being updated
transaction_id
string
The transaction ID that this payment is associated with, if any. This is present only when a payment was initiated using virtual accounts.
new_payment_status
string
The status of the payment.
PAYMENT_STATUS_INPUT_NEEDED: This is the initial state of all payments. It indicates that the payment is waiting on user input to continue processing. A payment may re-enter this state later on if further input is needed.
PAYMENT_STATUS_INITIATED: The payment has been successfully authorised and accepted by the financial institution. For successful payments, this is a potential terminal status. Further status transitions can be to REJECTED and, when supported by the institution, to EXECUTED.
PAYMENT_STATUS_INSUFFICIENT_FUNDS: The payment has failed due to insufficient funds.
PAYMENT_STATUS_FAILED: The payment has failed to be initiated. This error may be caused by transient system outages and is retryable once the root cause is resolved.
PAYMENT_STATUS_BLOCKED: The payment has been blocked by Plaid. This can occur, for example, due to Plaid flagging the payment as potentially risky. This is a retryable error.
PAYMENT_STATUS_AUTHORISING: The payment is currently being processed. The payment will automatically exit this state when the financial institution has authorised the transaction.
PAYMENT_STATUS_CANCELLED: The payment was cancelled (typically by the end user) during authorisation.
PAYMENT_STATUS_EXECUTED: The funds have successfully left the payer account and payment is considered complete. Not all institutions support this status: support is more common in the UK, and less common in the EU. For institutions where this status is not supported, the terminal status for a successful payment will be PAYMENT_STATUS_INITIATED.
PAYMENT_STATUS_SETTLED: The payment has settled and funds are available for use. A payment will typically settle within seconds to several days, depending on which payment rail is used. This status is only available to customers using Plaid Virtual Accounts.
PAYMENT_STATUS_ESTABLISHED: Indicates that the standing order has been successfully established. This state is only used for standing orders.
PAYMENT_STATUS_REJECTED: The payment was rejected by the financial institution.
Deprecated: These statuses will be removed in a future release.
PAYMENT_STATUS_UNKNOWN: The payment status is unknown.
PAYMENT_STATUS_PROCESSING: The payment is currently being processed. The payment will automatically exit this state when processing is complete.
PAYMENT_STATUS_COMPLETED: Indicates that the standing order has been successfully established. This state is only used for standing orders.

Possible values: PAYMENT_STATUS_INPUT_NEEDED, PAYMENT_STATUS_PROCESSING, PAYMENT_STATUS_INITIATED, PAYMENT_STATUS_COMPLETED, PAYMENT_STATUS_INSUFFICIENT_FUNDS, PAYMENT_STATUS_FAILED, PAYMENT_STATUS_BLOCKED, PAYMENT_STATUS_UNKNOWN, PAYMENT_STATUS_EXECUTED, PAYMENT_STATUS_SETTLED, PAYMENT_STATUS_AUTHORISING, PAYMENT_STATUS_CANCELLED, PAYMENT_STATUS_ESTABLISHED, PAYMENT_STATUS_REJECTED
old_payment_status
string
The status of the payment.
PAYMENT_STATUS_INPUT_NEEDED: This is the initial state of all payments. It indicates that the payment is waiting on user input to continue processing. A payment may re-enter this state later on if further input is needed.
PAYMENT_STATUS_INITIATED: The payment has been successfully authorised and accepted by the financial institution. For successful payments, this is a potential terminal status. Further status transitions can be to REJECTED and, when supported by the institution, to EXECUTED.
PAYMENT_STATUS_INSUFFICIENT_FUNDS: The payment has failed due to insufficient funds.
PAYMENT_STATUS_FAILED: The payment has failed to be initiated. This error may be caused by transient system outages and is retryable once the root cause is resolved.
PAYMENT_STATUS_BLOCKED: The payment has been blocked by Plaid. This can occur, for example, due to Plaid flagging the payment as potentially risky. This is a retryable error.
PAYMENT_STATUS_AUTHORISING: The payment is currently being processed. The payment will automatically exit this state when the financial institution has authorised the transaction.
PAYMENT_STATUS_CANCELLED: The payment was cancelled (typically by the end user) during authorisation.
PAYMENT_STATUS_EXECUTED: The funds have successfully left the payer account and payment is considered complete. Not all institutions support this status: support is more common in the UK, and less common in the EU. For institutions where this status is not supported, the terminal status for a successful payment will be PAYMENT_STATUS_INITIATED.
PAYMENT_STATUS_SETTLED: The payment has settled and funds are available for use. A payment will typically settle within seconds to several days, depending on which payment rail is used. This status is only available to customers using Plaid Virtual Accounts.
PAYMENT_STATUS_ESTABLISHED: Indicates that the standing order has been successfully established. This state is only used for standing orders.
PAYMENT_STATUS_REJECTED: The payment was rejected by the financial institution.
Deprecated: These statuses will be removed in a future release.
PAYMENT_STATUS_UNKNOWN: The payment status is unknown.
PAYMENT_STATUS_PROCESSING: The payment is currently being processed. The payment will automatically exit this state when processing is complete.
PAYMENT_STATUS_COMPLETED: Indicates that the standing order has been successfully established. This state is only used for standing orders.

Possible values: PAYMENT_STATUS_INPUT_NEEDED, PAYMENT_STATUS_PROCESSING, PAYMENT_STATUS_INITIATED, PAYMENT_STATUS_COMPLETED, PAYMENT_STATUS_INSUFFICIENT_FUNDS, PAYMENT_STATUS_FAILED, PAYMENT_STATUS_BLOCKED, PAYMENT_STATUS_UNKNOWN, PAYMENT_STATUS_EXECUTED, PAYMENT_STATUS_SETTLED, PAYMENT_STATUS_AUTHORISING, PAYMENT_STATUS_CANCELLED, PAYMENT_STATUS_ESTABLISHED, PAYMENT_STATUS_REJECTED
original_reference
string
The original value of the reference when creating the payment.
adjusted_reference
string
The value of the reference sent to the bank after adjustment to pass bank validation rules.
original_start_date
string
The original value of the start_date provided during the creation of a standing order. If the payment is not a standing order, this field will be null.

Format: date
adjusted_start_date
string
The start date sent to the bank after adjusting for holidays or weekends. Will be provided in ISO 8601 format (YYYY-MM-DD). If the start date did not require adjustment, or if the payment is not a standing order, this field will be null.

Format: date
timestamp
string
The timestamp of the update, in ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z"

Format: date-time
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "PAYMENT_INITIATION",
3  "webhook_code": "PAYMENT_STATUS_UPDATE",
4  "payment_id": "payment-id-production-2ba30780-d549-4335-b1fe-c2a938aa39d2",
5  "new_payment_status": "PAYMENT_STATUS_INITIATED",
6  "old_payment_status": "PAYMENT_STATUS_PROCESSING",
7  "original_reference": "Account Funding 99744",
8  "adjusted_reference": "Account Funding 99",
9  "original_start_date": "2017-09-14",
10  "adjusted_start_date": "2017-09-15",
11  "timestamp": "2017-09-14T14:42:19.350Z",
12  "environment": "production"
13}
Was this helpful?

transfer webhooks

Transfer webhooks

Learn how to use Transfer webhooks to receive notifications when new events are available

Enabling Transfer webhooks

An overview of webhooks at Plaid is available in the API Reference. There you can find general information on Plaid webhooks, including IP addresses, webhook verification, and retry logic.

To enable Transfer webhooks, add your endpoint on the account webhooks page of the dashboard. If you are not able to access the page, contact your Plaid Account Manager.

To confirm that your endpoint has been correctly configured, you can trigger a test webhook via /sandbox/transfer/fire_webhook.

Example integration

Upon receiving a TRANSFER_EVENTS_UPDATE webhook, poll the events sync endpoint to process the available events. Note that there may only be one new event, or there may be many new events. Plaid will send a maximum of approximately 1 webhook per minute as new events continue to become available, unless you are using Transfer webhooks for micro-deposit event notifications, in which case you will receive a separate webhook for each event.

1// Webhook received
2wait_for_and_ack_webhook();
3// Fetch the maximum event ID from your systems
4after_id = fetch_last_event_id();
5var events = [];
6
7// Poll event sync endpoint for all new events
8do {
9  // Fetch the next set of events and update after_id
10  events = plaidClient.transferEventSync(after_id);
11  after_id += len(events);
12
13  // Handle new events
14  for (event of events) {
15    yourEventHandler(event);
16  }
17} while (events.length > 0);

Transfer webhooks body

To view the schema and sample body for all available transfer webhooks, see the Transfer webhooks API reference.

Sample app code

For a real-life example of an app that incorporates the transfer webhook and tests it using the /sandbox/transfer/fire_webhook endpoint, see the Node-based Plaid Pattern Transfer sample app. Pattern Transfer is a sample subscriptions payment app that enables ACH bank transfers. The Transfer webhook handler can be found in handleTransferWebhook.js and the test which fires the webhook can be found at events.js

link oauth

OAuth Guide

Configure Link to connect to institutions via OAuth

Prefer to learn by watching? Video guides are available for this topic.

Introduction to OAuth

OAuth support is required in all Plaid integrations that connect to financial institutions. Without OAuth support, your end users will not be able to connect accounts from institutions that require OAuth, which includes several of the largest banks in the US. OAuth setup can be skipped only if your Plaid integration is limited to products that do not connect to financial institutions (Enrich, Identity Verification, Monitor, and Document Income).

OAuth is an industry-standard framework for authorization. With OAuth, end users can grant third parties access to their data without sharing their credentials directly with the third party.

Typically, end users authenticate and permission data directly within Plaid Link when connecting their financial accounts to third party applications. With OAuth, however, end users temporarily leave Link to authenticate and authorize data sharing using the institution's website or mobile app instead. Afterward, they're redirected back to Link to complete the Link flow and return control to the third party application.

A typical OAuth flow
A typical OAuth flow with Plaid Link

In addition, Plaid integrations with OAuth have several benefits over the traditional, non-OAuth experience in Link, such as:

  • Familiar and trustworthy experiences With OAuth, end users authenticate via the bank's website or mobile app, a familiar experience that can help with conversion.

  • Streamlined login experiences Some OAuth-enabled institutions (e.g., Chase) provide an "App-to-App" experience for end users if the end user has the institution's mobile app installed on their device. App-to-App can provide alternative authentication methods to end users (e.g., Touch ID or Face ID) that can help simplify and accelerate the authentication process.

  • Greater connection uptime You can generally expect greater connection uptime with OAuth-enabled institutions, which means fewer connection errors for end users when using Plaid Link.

  • Longer-lived connections Items at OAuth-enabled institutions generally remain connected longer. This typically results in fewer re-authentication errors (e.g., ITEM_LOGIN_REQUIRED).

  • Improved MFA (multi/second-factor) support OAuth-enabled institutions can support end user accounts that may be currently unsupported due to the end user's MFA settings.

OAuth support and compatibility

OAuth is supported on all platforms on which Link is supported.

Beginning September 30, 2023, Chase will no longer support in-process webview traffic via OAuth. The process described in this guide for webview integrations will walk you through creating compliant, out-of-process webview integrations. To learn more about how to convert existing in-process webview integrations, see the in-process webview deprecation notice.

Plaid supports the OAuth2 protocol. For a list of the largest Plaid-supported institutions that use OAuth in the US, consult the OAuth institutions page. For a full list of institutions, call /institutions/get endpoint with your desired country_codes and the oauth option set to true. Note that for an institution where a migration to OAuth is in progress, some Items may use OAuth, while other Items at the same institution may not.

Prerequisites for adding OAuth support

Ensure you have implemented Link tokens

OAuth requires the use of Link tokens. If you are using a legacy implementation with public keys rather than Link tokens, see the Link token migration guide.

Request Production access from Plaid

Production access is a prerequisite for supporting OAuth. Plaid will contact you once your account has been enabled for Production.

In the US and Canada, OAuth requires Production access; you cannot connect to US OAuth institutions in the Development environment without having received both OAuth approval and Production approval. You can, however, test OAuth in the Sandbox environment, using Sandbox-only institutions, without needing Production approval.

Complete the registration requirements

Before implementing support for OAuth institutions, be sure to complete the registration requirements in the Plaid Dashboard.

  • Application display information – This is public information that end users of your application will see when managing connections between your application and their bank accounts, including during OAuth flows. This information helps end users understand what your application is and why it is requesting access, which can improve conversion. In addition, some US institutions require your profile to be completed and will not allow apps with an empty profile to access their OAuth implementations.

  • Company information – Information about your company. This information is not shared with end users of your application and is only accessible to Plaid, members of your team, and financial institutions you register with.

If you later need to update your company information or application display information, you can do so at any time via the Dashboard.

  • Plaid Master Services Agreement – (US/CA only) Your latest contract with Plaid. If this is marked as incomplete, please reach out to your account manager or contact support for an updated version.

  • Plaid security questionnaire – (US/CA only) You must complete a questionnaire about your company's risk and security practices before accessing certain bank APIs. Because it may take some time for Plaid to review, it is recommended that you submit this questionnaire as early as possible in the integration process. If your Plaid integration process is otherwise complete but your security questionnaire has not yet been approved, contact your account manager or submit a Support ticket.

Implementing OAuth support

Required steps

  1. Create and register a redirect URI

  2. Generate a Link token and configure it with your redirect URI

  3. Reinitialize Link at your redirect URI

  4. Wait for OAuth approval from Plaid, which can be tracked on the OAuth institution page.

  5. Understand institution-specific behaviors and, if necessary, update your app to support them.

Recommended, optional steps

  1. Handle Link OAuth events

  2. Listen for consent expiration webhooks

  3. Manage consent revocation

  4. (US/CA only) Enable OAuth and migrate users

  5. (Europe only) Enable QR Code authentication

Create and register a redirect URI

After successfully completing the OAuth flow via their bank's website or app, you'll need to redirect the end user back to your application. This is accomplished with a redirect URI that you'll need to set up and configure accordingly depending on your client platform.

Constructing valid redirect URIs

Redirect URIs must use HTTPS. The only exception is on Sandbox, where, for testing purposes, redirect URIs pointing to localhost are allowed over HTTP. Custom URI schemes are not supported in any environment. Subdomain wildcards are supported using a * character. For example, adding https://*.example.com/oauth.html to the allowlist permits https://oauth1.example.com/oauth.html, https://oauth2.example.com/oauth.html, etc. Subdomain wildcards can only be used for domains that you control and are not allowed for domains on the Public Suffix List. For example, https://*.co.uk/oauth.html is not a valid subdomain wildcard. Redirect URIs do not support hash routing, so your URI cannot contain a '#' symbol.

Note: Do not enter a wildcard (*) when specifying a redirect_uri in the call to /link/token/create. Wildcards are reserved for the allowlist on the dashboard only.

Desktop web, mobile web, React, or Webview

For desktop web, mobile web, or React, the redirect URI is typically the address of a blank web page you'll need to create and host. This web page will be used to allow the end user to resume and complete the Link flow after completing the OAuth flow on their bank's website or app. https://example.com/oauth-page.html is an example of a typical redirect URI. After creating your redirect URI, add it to the Allowed redirect URIs.

Redirect URIs and desktop & mobile web

OAuth flows will function properly on web even if you don't set up a redirect URI. Desktop web and mobile web integrations will always try to open the OAuth bank's website in a new pop-up window if possible (or in a new tab on mobile web), regardless of whether a redirect_uri is provided. However, not providing a redirect URI will prevent mobile web users from using your integration through a webview browser (a browser launched via Mail, Facebook, Google Maps, etc.) because those browsers often do not support pop-ups. To provide the best experience for end users on mobile web, always specify a redirect URI and reinitialize Link.
Setting a redirect_uri is still required for Link web SDK integrations within a mobile application (e.g within a webview) because those integrations still use the redirect OAuth flow.

iOS SDK, React Native (iOS)

To maintain support for Chase OAuth flows, all integrations must upgrade to version 4.1.0 of the Link iOS SDK or version 9.0.1 of the React Native SDK (released January 2023) by September 30, 2023.

For iOS SDK or React Native (iOS), the redirect URI is typically the address of a blank web page you'll need to create and host. You'll need to configure an Apple App Association File to associate your redirect URI with your application. To enable App-to-App authentication flows, you'll need to register the redirect URI as an app link. Custom URI schemes are not supported; a proper universal link must be used.

Android SDK, React Native (Android)

Register your Android package by adding the Android package name(s) to the Allowed Android package names list. Plaid will automatically create your redirect URI and its contents based on your package name. When specifying a redirect URI in the following steps, you will use android_package_name.

Configure your Link token with your redirect URI

OAuth support requires use of Link tokens. The legacy client-side settings oauthRedirectUri and oauthNonce are ignored and will not be read. If you are still using a legacy public key, see the Link token migration guide.

You'll need to specify your redirect URI via the redirect_uri field when generating a Link token with /link/token/create (on Android, use the android_package_name parameter to provide your Android package name instead). Use this Link token to initialize Link.

If you're using Link in update mode, ensure you specify your redirect URI via the redirect_uri field (on Android, use the android_package_name parameter to provide your package name instead).

Do not use query parameters when specifying the redirect_uri. Make sure to specify the user.client_user_id.

Select group for content switcher
Select Language
1const request = {
2  user: {
3    // This should correspond to a unique id for the current user.
4    client_user_id: 'user-id',
5  },
6  client_name: 'Plaid Test App',
7  products: [Products.Transactions],
8  country_codes: [CountryCode.Us],
9  language: 'en',
10  webhook: 'https://sample-web-hook.com',
11  redirect_uri: 'https://example.com/callback',
12};
13
14try {
15  const createTokenResponse = await client.linkTokenCreate(request);
16  const linkToken = response.data.link_token;
17} catch (error) {
18  // handle error
19}
Using OAuth within an iFrame

Launching Link from within an iFrame is not recommended. Link conversion for OAuth institutions is typically up to 15 percentage points higher when using Plaid's SDKs than when using iFrames. If Link is launched from within an iFrame, you'll be unable to maintain user state. Page rendering, sizing, and data exchange may also be suboptimal.

Reinitializing Link

After completing the OAuth flow, the end user will be redirected to your redirect URI (e.g., https://example.com/oauth-page.html). This is where they'll resume and complete the Link flow and return to your application. To do this, you'll need to reinitialize Link at your redirect URI.

Depending on your client platform, Link may require additional configuration to work with OAuth. Detailed instructions for each platform are provided below.

Client platformLink reinitialization required?
Desktop webNo
Mobile webNot required, but recommended in order to maximize Link conversion
WebviewYes
iOS SDKNo
React Native (iOS)No
Android SDK (version 3.2.3 or later required)No, but app package registration required
React Native (Android)No, but app package registration required
Desktop web, mobile web, or React

A reference implementation for OAuth in React can be found in the Plaid React GitHub. If you are looking for a demonstration of a real-life app that incorporates the implementation of OAuth in React see Plaid Pattern, a Node-based example app.

For desktop web, mobile web, or React, you'll need to launch Link twice, once before the OAuth redirect (i.e., the first Link initialization) and once after the OAuth redirect (i.e., Link reinitialization). The Link reinitialization should occur at your redirect URI.

When reinitializing Link, configure it using the same Link token you used when initializing Link the first time. It is up to you to determine the best way to provide the correct link_token upon redirect. As an example, the code sample below demonstrates the use of a browser's local storage to retrieve the Link token from the first Link initialization.

Select group for content switcher
1import React, { useEffect } from 'react';
2import { usePlaidLink } from 'react-plaid-link';
3
4const OAuthLink = () => {
5  // The Link token from the first Link initialization
6  const linkToken = localStorage.getItem('link_token');
7
8  const onSuccess = React.useCallback((public_token: string) => {
9    // send public_token to server, retrieve access_token and item_id
10    // return to "https://example.com" upon completion
11  });
12
13  const onExit = (err, metadata) => {
14    // handle error...
15  };
16
17  const config: Parameters<typeof usePlaidLink>[0] = {
18    token: linkToken!,
19    receivedRedirectUri: window.location.href, //the redirect URI with an OAuth state ID parameter
20    onSuccess,
21    onExit,
22  };
23
24  const { open, ready, error } = usePlaidLink(config);
25
26  // automatically reinitialize Link
27  useEffect(() => {
28    if (ready) {
29      open();
30    }
31  }, [ready, open]);
32
33  return <></>;
34};
35
36export default OAuthLink;

In addition, when reinitializing Link, you should configure it with the receivedRedirectUri field and pass in the full received redirect URI, as demonstrated in the code sample. The received redirect URI is your redirect URI appended with an OAuth state ID parameter. The OAuth state ID parameter will allow you to persist user state when reinitializing Link, allowing the end user to resume the Link flow where they left off. No extra configuration or setup is needed to generate the received redirect URI. The received redirect URI is programmatically generated for you by Plaid after the end user authenticates on their bank's website or mobile app. You can retrieve it using window.location.href.

The received redirect URI must not contain any extra query parameters or fragments other than what is provided upon redirect. The standard Link callback onSuccess will be triggered as usual once the user completes the Link flow.

1https://example.com/oauth-page.html?oauth_state_id=9d5feadd-a873-43eb-97ba-422f35ce849b`

If Link is reinitialized in the same browser session as the first Link initialization, you can store the Link token in a cookie or local storage in the browser for easy access when reinitializing Link. For example, the Plaid Quickstart uses localStorage.setItem to store the token.

If Link is reinitialized in a different browser session than the first Link initialization, you can store a mapping of the Link token associated with the user (server-side). Upon opening the second browser session, authenticate the user, fetch the corresponding Link token from the server, and use it to reinitialize Link.

Webview

Beginning September 30, 2023, all webview-based integrations will need to extend the webview handler for redirects in order to support Chase OAuth. This can be accomplished with code samples for iOS and Android For more details, see Extending webview instances to support certain institutions.

For webview, you'll need to launch Link twice, once before the OAuth redirect (i.e., the first Link initialization) and once after the OAuth redirect (i.e., Link reinitialization). The Link reinitialization should occur at your redirect URI.

For the initial Link instance, first generate a Link token as described in Configure your Link token with your redirect URI, then set Link's token parameter to this Link token. After the end user successfully completes the OAuth flow via their bank's website or app, they'll be redirected to your redirect URI, where you'll reinitialize Link.

1https://cdn.plaid.com/link/v2/stable/link.html?isWebview=true
2&token=GENERATED_LINK_TOKEN

When reinitializing Link, use the same Link token you generated when you first initialized Link. It is up to you to determine the best way to provide the correct link_token upon redirect.

In addition, when reinitializing Link, you should configure it with the receivedRedirectUri field. The received redirect URI is your redirect URI appended with an OAuth state ID parameter. The OAuth state ID parameter will allow you to persist user state when reinitializing Link, allowing the end user to resume the Link flow where they left off. No extra configuration or setup is needed to generate the received redirect URI. The received redirect URI is programmatically generated after the end user authenticates on their bank's website or mobile app. The received redirect URI must not contain any extra query parameters or fragments other than what is provided upon redirect. Note that any unsafe ASCII characters in the receivedRedirectUri in the webview query string must be URL-encoded; for improved readability, the example below is shown prior to URL encoding.

1https://cdn.plaid.com/link/v2/stable/link.html?isWebview=true
2&token=SAME_GENERATED_LINK_TOKEN&receivedRedirectUri=https://example.com/oauth-page?oauth_state_id=9d5feadd-a873-43eb-97ba-422f35ce849b
Extending webview instances to support certain institutions

Some institutions require further modifications to work with mobile webviews. This applies to USAA on Android and Chase app-to-app on Android. Beginning on September 30, 2023, this also applies to all Chase webview integrations. For these institutions, you'll need to extend your Webview instance to override the handler for redirects. An example function for Android and an example function for iOS can be found within Plaid's Link examples on GitHub and can be copied for use with your app.

On Android, you will also need to support Android App links to have a valid working redirect_uri to provide to /link/token/create. This requires creating a ./well_known/assetlinks.json and an IntentFilter on the Android app.

iOS

To maintain support for Chase OAuth flows, all integrations must upgrade to version 4.1.0 of the Link iOS SDK (released January 2023) by September 30, 2023.

For the initial Link instance, first generate a Link token as described in Configure your Link token with your redirect URI. Your redirect_uri must also be added to the Plaid dashboard and should be configured as a universal link (not a custom URI) using an Apple App Association File.

Select Language
1// With custom configuration
2let linkToken = "<#GENERATED_LINK_TOKEN#>"
3let onSuccess: (LinkSuccess) -> Void = { (success) in
4  // Read success.publicToken here
5  // Log/handle success.metadata here
6}
7let linkConfiguration = LinkTokenConfiguration(linkToken: linkToken, onSuccess: onSuccess)
8let handlerResult = Plaid.create(linkConfiguration)
9
10switch handlerResult {
11case .success(let handler):
12  self.handler = handler
13  handler.open(presentUsing: .viewController(self))
14case .failure(let error):
15  // Log and handle the error here.
16}

OAuth on iOS devices can occur fully within the integrating application (In-App OAuth), or it can include a transition from your application to the bank's app (App-to-App OAuth). App-to-App OAuth is initiated by the bank itself and is not controlled by the iOS SDK. In order to ensure your users can return to your application, you must support App-to-App OAuth.

App-to-App OAuth requirements

During App-to-App OAuth, the end user is directed from your application to the bank's app to authenticate. To return the end user back to your application after they authenticate, your redirect URI must be a universal link. Once the user returns to your app, UIKit will invoke a method within your application and provide the redirect URI that triggered this return to the app.

App-to-App behavior can be tested in the Sandbox environment. If App-to-App does not function as intended, validate that the redirect URI used to configure Link is a valid universal link and that your application has the associated-domains entitlement for that URI.

React Native on iOS

To maintain support for Chase OAuth flows, all integrations must upgrade to version 9.0.1 of the React Native SDK (released January 2023) by September 30, 2023.

An example React Native client implementation for OAuth on iOS can be found in the Tiny Quickstart.

React Native on iOS uses universal links for OAuth. You will need to create and register a redirect URI and configure your Link token with your redirect URI in order for OAuth to work correctly.

Android SDK and Android on React Native

Example code for implementing OAuth on Android can be found on GitHub in the Android SDK. An example React Native client implementation for OAuth on Android can be found in the Tiny Quickstart.

When using the Android SDK or Android on React Native, you must generate a Link token by calling /link/token/create and passing in an android_package_name. Your package name (e.g., com.example.testapp) must also be added to the Plaid dashboard. Do not pass a redirect_uri into the /link/token/create call. Proceed to initialize Link with the generated token.

Select group for content switcher
1String clientUserId = "user-id";
2
3LinkTokenCreateRequestUser user = new LinkTokenCreateRequestUser()
4  .clientUserId(clientUserId)
5  .legalName("legal name")
6  .phoneNumber("4155558888")
7  .emailAddress("email@address.com");
8
9LinkTokenCreateRequest request = new LinkTokenCreateRequest()
10  .user(user)
11  .clientName("Plaid Test App")
12  .products(Arrays.asList(Products.AUTH))
13  .countryCodes(Arrays.asList(CountryCode.US))
14  .language("en")
15  .webhook("https://example.com/webhook")
16  .linkCustomizationName("default")
17  .androidPackageName("com.plaid.example")
18
19Response<LinkTokenCreateResponse> response = client()
20  .linkTokenCreate(request)
21  .execute();
22
23String linkToken = response.body().getLinkToken();

Testing OAuth

You can test OAuth on Sandbox even if Plaid has not yet enabled OAuth flows for your account. To test out the OAuth flow in the Sandbox environment, you can use Platypus OAuth Bank (ins_127287), Platypus OAuth App2App Bank (ins_132241) for testing App2App flows on mobile, or to emulate European flows, Flexible Platypus Open Banking (ins_117181). These dummy institutions direct you to a Plaid sample OAuth flow that is similar to what you would see for a bank’s OAuth flow. When prompted, you can enter anything as credentials (including leaving the input fields blank) to proceed through the sample OAuth flow. Note that institution-specific OAuth flows cannot be tested in Sandbox; OAuth panes for Platypus institutions will be shown instead.

To ensure your OAuth integration works across all platforms, test it in the following scenarios before deployment:

  • On each client platform that is available to your users (e.g. desktop, iOS app, iOS mobile web, Android app, Android mobile web)
  • With the OAuth institution app installed, for institutions that support app-to-app authentication (i.e. Chase). For more details on testing app-to-app in Sandbox, see App-to-App authentication.
  • Without the OAuth institution app installed
  • In update mode, by using /sandbox/item/reset_login in the Sandbox environment

All environments, including Sandbox, use the pop-up flow on desktop and mobile web, unless the page is accessed through a mobile webview. To test the redirect flow, you can use your browser's developer tools to simulate running your application in a webview browser, such as Chrome WebView. On Chrome, for example, select the "Toggle Device Toolbar" option from within Chrome's Developer Tools and create a new virtual device configuration with a WebView user agent.

1Mozilla/5.0 (Linux; Android 5.1.1; Nexus 5 Build/LMY48B; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/43.0.2357.65 Mobile Safari/537.36

In the Sandbox environment, all product-specific permissions will be granted in the OAuth flow, regardless of whether you check the boxes to share account and routing number or identity information.

Troubleshooting common OAuth problems

For guides to troubleshooting common OAuth issues, see Link troubleshooting.

Enabling OAuth connections and migrating users

Your integration will automatically convert to using OAuth connections for a given institution on the date that Plaid has indicated to you. You may also have the option to migrate to OAuth earlier; if this option is available, a button to enable OAuth for the institution will appear on the OAuth institution page.

Your existing Items with the institution being migrated will automatically be moved into the ITEM_LOGIN_REQUIRED state. This will happen gradually over a migration period (by default, 90 days, but the duration may vary depending on the institution), starting on or shortly after the OAuth enablement date. Completing the update mode flow for these Items will convert them to use OAuth connections. To avoid any disruption in connectivity, you can also prompt your users to complete the update mode flow as soon as you have been enabled for OAuth with their institution.

Institution-specific behaviors

Some institutions have unique behaviors when used with OAuth connections. Note that these behaviors are standard for any connection using these institutions' APIs and not specific to their integration with Plaid.

The behaviors listed below are the ones most likely to require changes to your application's business logic; for a more exhaustive list of institution-specific OAuth details, see the "Bank-specific documentation" section of the OAuth integration PDF guide.

Chase

When used with Auth, Chase will return "tokenized" routing and account numbers, which can be used for ACH transactions but are not the user's actual account and routing numbers. The mask, however, will continue to be based on the actual account number. For this reason, when displaying account numbers from Chase to the user to help them identify their account in your UI, always use the mask rather than displaying the account number. If a user revokes their permissions to your app, the tokenized numbers will continue to work for ACH deposits, but not withdrawals. For more details, see the API reference.

Update mode cannot be used to remove accounts or permissions from a Chase Item. If your end user wishes to revoke or limit Plaid's access to a Chase account, they must do so via the Chase Security Center within the Chase online banking portal. This occurs even across Items; if a Chase Item is deleted and a new Item is created for your app using the same credentials, the previously selected permissions will persist to the new Item.

Existing Chase OAuth Items will be invalidated when a new public token is created using the same credentials. For more details, see Preventing duplicate Items.

Capital One

Capital One does not support real-time on-demand data updates. When calling /accounts/balance/get for Capital One, you will need to specify how fresh you require the balance data to be. If balance data meeting your requirements is not available, the call will fail and you will not be billed. For more details, see the API Reference. For similar reasons, /transactions/refresh will result in a PRODUCT_NOT_SUPPORTED error if used on a Capital One Item.

Charles Schwab

Existing Schwab OAuth Items will be invalidated when a new public token is created using the same credentials. For more details, see Preventing duplicate Items.

Handling Link events

OAuth flows have a different sequence of Link events than non-OAuth flows. If you are using Link events to measure conversion metrics for completing the Link process, you may need to handle these events differently when using OAuth.

In addition, the flow itself may be different if you are initiating OAuth with a redirect URI or displaying the OAuth screen in a separate pop-up window.

The events fired for a non-OAuth flow might look something like this:

1OPEN (view_name = CONSENT)
2TRANSITION_VIEW view_name = SELECT_INSTITUTION)
3SELECT_INSTITUTION
4TRANSITION_VIEW (view_name = CREDENTIAL)
5SUBMIT_CREDENTIALS
6TRANSITION_VIEW (view_name = LOADING)
7TRANSITION_VIEW (view_name = MFA, mfa_type = code)
8SUBMIT_MFA (mfa_type = code)
9TRANSITION_VIEW (view_name = LOADING)
10TRANSITION_VIEW (view_name = CONNECTED)
11HANDOFF
12onSuccess

The events fired for a typical OAuth flow may look more like the following:

1OPEN (view_name = CONSENT)
2TRANSITION_VIEW (view_name = SELECT_INSTITUTION)
3SELECT_INSTITUTION
4TRANSITION_VIEW (view_name = OAUTH)
5OPEN_OAUTH
6...
7(The user completes the OAuth flow at their bank)
8...
9TRANSITION_VIEW (view_name = CONNECTED)
10HANDOFF
11onSuccess

Link does not issue the SUBMIT_CREDENTIALS event when a user authenticates with an institution that requires OAuth. Link issues the OPEN_OAUTH event when a user chooses to be redirected to the institution’s OAuth portal. It is recommended to track this event instead of SUBMIT_CREDENTIALS.

In most situations, if Plaid encounters an error from the bank's OAuth flow, or if the user chooses to not grant access via their OAuth login attempt, the user will return to your application and Link will fire an EXIT event with a requires_oauth exit status. You may also see an ERROR event, depending on the type of error that Plaid encountered.

1SELECT_INSTITUTION
2OPEN (view_name = null)
3ERROR (error_code = INTERNAL_SERVER_ERROR)
4TRANSITION_VIEW (view_name = ERROR)
5TRANSITION_VIEW (view_name = EXIT)
6EXIT (exit_status = requires_oauth)

If the user closes the bank's OAuth window without completing the OAuth flow, Link will fire a CLOSE_OAUTH event. This only happens in situations where the OAuth flow appears in a pop-up window.

If the OAuth flow times out while waiting for the user to sign in, Link will fire a FAIL_OAUTH event. This only happens in situations where the OAuth flow appears in a pop-up window.

Once you receive the onSuccess callback from an OAuth flow, the integration steps going forward are the same as for non-OAuth flows.

Refreshing Item consent

Some institutions require users to periodically re-affirm their consent to avoid Item expiration. When using OAuth, end users may need to refresh their access-consent after a certain amount of time, such as one year or three months. This is particularly common in Europe, where access-consent typically expires after 90 days. Expiring access-consent is less common in the US, and consent periods are typically longer. For more details on which US institutions expire access-consent and how frequently, see the "Bank-specific documentation" section (section 8) of the OAuth integration PDF guide.

To determine when a user will need to re-authenticate, make a request to the /item/get endpoint and note the consent_expiration_time field. Plaid will also send a PENDING_EXPIRATION webhook one week before a user’s access-consent is set to expire. In order to continue receiving data for that user without interruption, ensure they re-authenticate via update mode prior to that date. When using Link in update mode, be sure to specify your redirect URI via the redirect_uri field as described in Configure your Link token with your redirect URI.

If consent is not refreshed before the Item expires, the Item will enter the ITEM_LOGIN_REQUIRED error state. Sending the Item through update mode, as described above, will resolve the error.

For a real-life example of handling the PENDING_EXPIRATION webhook and update mode, see handleItemWebhook.js, linkTokens.js and launchLink.tsx. These files illustrate the code for handling of webhooks and update mode for Plaid Link for React for the Node-based Plaid Pattern sample app.

Managing consent revocation

Many institutions that support OAuth provide a means for the end user to revoke consent via their website. If an end user revokes consent, the Item will enter an ITEM_LOGIN_REQUIRED state after approximately 24-48 hours.

If an Item is enabled for either OAuth or Account Select v2, a user may also revoke consent for a single account, without revoking consent for the entire Item. Accounts in this situation are treated the same as accounts that have been closed: no webhook will be fired, you will stop receiving transactions associated with the account, and Plaid will stop returning the account in API responses. Access can be re-authorized via the update mode flow.

When a user revokes access to an Item or an account, we recommend giving them the opportunity to either verify that they intended to remove it or to indicate that the revocation was unintentional. If the user did not mean to revoke access, they can re-authorize access by going through the standard update mode flow. If the user verifies that their action was intentional or does not respond after a few days, delete the associated data, and, in the case of a removed Item, use /item/remove to delete the Item altogether.

When using Link in update mode (for either case described in this section), be sure to specify your redirect URI via the redirect_uri field as described in Configure your Link token with your redirect URI.

Partial consent

OAuth can provide the ability for end users to configure granular permissions on their Items. For example, an end user may allow access to a checking account but not a credit card account behind the same login, or may allow an institution to share only certain account information, such as identity data but not transaction history.

Before handing the user off to the institution's OAuth flow, Plaid will provide guidance within Link recommending which permissions the user needs to grant based on which products you have initialized Link with. In Production and Development, this guidance will be tailored to use the same wording that the institution's OAuth flow uses. This guidance will appear both on initial link and during the update mode flow. For more details on the exact appearance and messaging used, see the OAuth Guide within the Dashboard.

If an end user chooses not to share data that is required by your Link token's products configuration, or does not share access to any accounts, the Link attempt will fail. In this case, they will need to restart the Link flow.

Note that if your app calls /link/token/create using an account_filter parameter to limit the account types that can be used with Link, the filter will only be applied after the OAuth flow has been completed and will not affect the permission selection interface within the OAuth flow.

If your app later needs to request access to a product or account that was not originally granted for that Item during Link, you can send the user to the update mode flow to authorize additional permissions. When using Link in update mode, be sure to specify your redirect URI via the redirect_uri field as described in Configure your Link token with your redirect URI.

App-to-App authentication

Some banks (i.e. Chase) support an App-to-App experience if the user is authenticating on their mobile device and has the bank's app installed. Instead of logging in via the bank's site, the bank's app will be launched instead, from which the user will be able to log in (including via TouchID or Face ID) before being redirected back to your app. Support for App-to-App should be automatic once you have implemented support for OAuth on mobile with any of Plaid's mobile SDKs. Note that on iOS, this requires configuring an Apple App Association file to associate your redirect URI with your app, as described under Create and register a redirect URI. If using webviews, App-to-App support is not automatic; for an App-to-App experience, it is strongly recommended to use a Plaid mobile SDK instead.

The full App-to-App flow can be tested in the Sandbox environment. You can test that your universal link works correctly using the Platypus OAuth App2App Bank (ins_132241) test institution. The bank's 'app' for this test institution will be a mobile web browser, but the universal link will function as expected if configured correctly, switching back to your app on handoff.

Chase is currently the only bank that supports App-to-App authentication on Plaid.

QR code authentication

For many European institutions, Plaid supports the ability for an end user to authenticate via their bank's mobile app – even if the user's journey begins in a desktop-based web session – in order to optimize for conversion. After the user selects an institution, they will be presented with the choice to scan a QR code and authenticate in the bank’s mobile app or to continue on desktop. When the user scans the QR code, they will be redirected to the bank’s app (or website, if the user does not have the app installed). After the user completes the OAuth flow, they will be redirected to a Plaid-owned page instructing them to return to their desktop to complete the flow.

To enable QR authentication, contact your Plaid account manager or file a Support ticket. No changes to your Link OAuth implementation are required to enable this flow.

To test out the QR code flow in the Sandbox environment, you can use Flexible Platypus Open Banking (ins_117181). When you launch Link with this institution selected in Sandbox, the QR code authentication flow will be triggered. The Sandbox institution does not direct you to a real bank's mobile app, but allows you to grant, deny, or simulate errors from the placeholder OAuth page instead.

Supported institutions for QR code authentication
Institution nameInstitution ID
Bank of Scotland - Personalins_118274
Bank of Scotland - Businessins_118276
Barclays (UK) - Mobile Banking: Businessins_118512
Barclays (UK) - Mobile Banking: Personalins_118511
Barclays (UK) - Mobile Banking: Wealth Managementins_118513
First Directins_81
Halifaxins_117246
HSBC (UK) - Businessins_118277
HSBC (UK) - Personalins_55
Lloyds Bank - Business and Commercialins_118275
Lloyds Bank - Personalins_61
Monzoins_117243
Nationwide Building Societyins_60
NatWest - Current Accountsins_115643
Revolutins_63
Royal Bank of Scotland - Current Accountsins_115642
Santander (UK) - Personal and Businessins_62
Starlingins_117520
Tesco (UK)ins_118393
TSBins_86
Ulster Bank (UK)ins_117734

errors invalid result

Invalid Result errors

Guide to troubleshooting invalid result errors

LAST_UPDATED_DATETIME_OUT_OF_RANGE

No data is available from the Item within the specified date-time.
Common causes
  • /accounts/balance/get was called with a parameter specifying the minimum acceptable data freshness, but no balance data meeting those requirements was available from the institution.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_RESULT",
4 "error_code": "LAST_UPDATED_DATETIME_OUT_OF_RANGE",
5 "error_message": "requested datetime out of range, most recently updated balance 2021-01-01T00:00:00Z",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

PLAID_DIRECT_ITEM_IMPORT_RETURNED_INVALID_MFA

The Plaid Direct Item import resulted in invalid MFA.
Common causes
  • No known causes.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_RESULT",
4 "error_code": "PLAID_DIRECT_ITEM_IMPORT_RETURNED_INVALID_MFA",
5 "error_message": "Plaid Direct Item Imports should not result in MFA.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

virtual accounts payouts

Payouts

Send funds from your virtual account

A payout represents the flow of funds from a client’s virtual account to an end user. A payout can be for an arbitrary amount if you have sufficient funds stored in your virtual account to cover the payout. Using Payouts requires integrating with virtual account API routes and receiving transaction webhooks.

Execute a Payout

Make sure your virtual account is set up before following these steps. For more information on setting up an account, see Managing virtual accounts.

  1. Call /wallet/get to check your virtual account balance.

    • If you have insufficient funds to make your desired payout, make sure to fund your virtual account before proceeding. After funding your virtual account, another request to /wallet/get will show the updated balance.

  2. Call /wallet/transaction/execute and store the transaction_id and status from the response.

Testing Payouts

You can begin testing Payouts in Sandbox by following the steps listed in the Add Virtual Accounts to your App guide. For Production access you will first need to submit a product access request Support ticket.

transactions webhooks

Transactions webhooks

Listen for Transaction webhooks to learn when transactions are ready for retrieval or when transactions have been updated.

Introduction

Webhooks are a useful part of the Transactions product that notifies you when Plaid has new or updated transaction information. This guide will explain how to use webhooks to make sure you have up-to-date transaction history.

Configuring Link for transactions webhooks

Before you can listen to webhooks, you must first set up an endpoint and tell Plaid where to find it. To tell Plaid where to send its webhooks, send your webhook endpoint URL as an optional argument via the webhook parameter to /link/token/create.

You must also initialize your Item with Transactions by including transactions in the products array provided to /link/token/create. If you do not do this, Plaid will not attempt to retrieve any transactions for your Item until after /transactions/sync or /transactions/get is called for the first time. For more information, see Choosing when to initialize products.

Integrating the update notification webhook

After /transactions/sync is called for the first time on an Item, SYNC_UPDATES_AVAILABLE webhooks will begin to be sent to the configured destination endpoint.

This webhook will fire whenever any change has happened to the Item's transactions. The changes can then be retrieved by calling /transactions/sync with the cursor from your last sync call to this Item.

If at least 30 days of history is available with an update, the initial_update_complete parameter in the body of the SYNC_UPDATES_AVAILABLE webhook will be true. Similarly, historical_update_complete will be true if the full history (up to 24 months) is available.

For a real-life example that illustrates how to handle this webhook, see handleTransactionsWebhook.js, which contains the webhook handling code for the Node-based Plaid Pattern app.

Forcing transactions refresh

Sometimes, checking for transactions a few times a day is not good enough. For example, you might want to build a refresh button in your app that allows your user to check for updated transactions on-demand. To accomplish this, you can use the /transactions/refresh product. After a successful call to /transactions/refresh, if there are new updates, SYNC_UPDATES_AVAILABLE will be fired (along with DEFAULT_UPDATE and, if applicable, TRANSACTIONS_REMOVED).

Instructions for integrations using /transactions/get

The content in this section and below applies only to existing integrations using the /transactions/get endpoint. It is recommended that any new integrations use /transactions/sync instead of /transactions/get, for easier and simpler handling of transaction state changes. For information on migrating an existing /transactions/get integration to /transactions/sync, see the Transactions Sync migration guide.

When you first connect an Item in Link, transactions data will not immediately be available. INITIAL_UPDATE and HISTORICAL_UPDATE are both webhooks that fire shortly after an Item has been initially linked and initialized with the Transactions product. These webhooks will let you know when your transactions are ready. INITIAL_UPDATE fires first, after Plaid has successfully pulled 30 days of transactions for an Item. The HISTORICAL_UPDATE webhook fires next, once all historical transactions data is available. INITIAL_UPDATE typically fires within 10 seconds, and HISTORICAL_UPDATE within 1 minute, although these webhooks may take 2 minutes or more. The time required for the webhooks to fire will depend on the institution, as well as on the number of transactions being processed.

If you attempt to call /transactions/get before INITIAL_UPDATE has fired, you will get a PRODUCT_NOT_READY error. If you attempt to call /transactions/get after INITIAL_UPDATE has fired, but before HISTORICAL_UPDATE has fired, you will only be able to receive the last 30 days of transaction data. If you did not initialize the Item with Transactions, your first call to /transactions/get will result in a PRODUCT_NOT_READY error and kick off the process of readying transactions. You can then listen for the INITIAL_UPDATE or HISTORICAL_UPDATE webhooks to begin receiving transactions.

Updating transactions

Plaid fires two types of webhooks that provide information about changes to transaction data: DEFAULT_UPDATE and TRANSACTIONS_REMOVED.

Adding new transactions

The DEFAULT_UPDATE webhook fires when new transactions are available. Typically, Plaid will check for transactions once every 6 hours, but may check less frequently (such as once every 24 hours) depending on factors such as the institution and account type. If new transactions are available, the DEFAULT_UPDATE webhook will fire.

To reflect up-to-date transactions for a user in your app, handle the DEFAULT_UPDATE webhook by fetching more transactions. We recommend fetching about 7-14 days of transactions in response to DEFAULT_UPDATE. This is typically enough history to ensure that you haven't missed any transactions, but not so much that performance or rate limiting is likely to be a problem.

Once you've fetched these transactions, you will need to identify which transactions are new and which are duplicates of existing data that you have. You should not rely on the number in the webhook's new_transactions field to identify duplicates, since it can be unreliable. For example, new transactions may arrive between your receipt of the webhook and your call to /transactions/get. Instead, compare the transaction_id field of each newly fetched transaction to the transaction_id fields of your existing transactions, and skip the ones that you already have. For an example, see Plaid Pattern.

Removing stale transactions

The TRANSACTIONS_REMOVED webhook fires when transactions have been removed. The most common reason for this is in the case of pending transactions. In general, transactions start out as pending transactions and then move to the posted state one to two business days later. When Plaid detects that a transaction has moved from pending to posted state, the pending transaction as returned by /transactions/get is not modified. Instead, the pending transaction is removed, and a new transaction is added, representing the posted transaction. For a detailed explanation of pending and posted transactions and how they are handled by Plaid, see Transaction states.

Pending transactions can also be removed when they are canceled by the bank or payment processor. A transaction may be removed if its details are changed by the bank so extensively that Plaid can no longer recognize the new and old versions of the transaction as being the same (e.g., a transaction amount and description both being changed simultaneously). In this case, the old transaction will be deleted and a new transaction with the new details will be added. This "transaction churn" can affect both pending and posted transactions.

The TRANSACTIONS_REMOVED webhook contains the transaction IDs of the removed transactions, which you can use to identify and remove the corresponding transactions in your own application to avoid presenting duplicated or inaccurate data. If you encounter any problems with the webhook, you can also manually query transaction history for deleted transactions using logic similar to that recommended for handling the DEFAULT_UPDATE webhook.

transactions transactions data

Transaction states

Learn about the differences between pending and posted transactions

Pending and posted transactions

There are two types of transactions: pending and posted. A transaction begins its life as a pending transaction, then becomes posted once the funds have actually been transferred. It typically takes about one to five business days for a transaction to move from pending to posted, although it can take up to fourteen days in rare situations.

When a transaction posts, the transition from a pending to posted transaction will be represented through the /transactions/sync endpoint with the pending transaction's id in the removed field of the response and the new posted transaction in the added section of the response -- note that these aren't guaranteed to be in the same page, but should happen within the same overall update. If Plaid matches the pending transaction to the new posted transaction, the pending transaction's id will be marked in the pending_transaction_id of the posted transaction.

1{
2  "added": [{
3    "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
4    "pending_transaction_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
5    "pending": false,
6    "name": "Apple Store",
7    "amount": 2307.21
8    /* ... */
9  }],
10  "removed": [{
11    "transaction_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
12    "pending": true,
13    "name": "Apple Store",
14    "amount": 2307.21
15    /* ... */
16  }],
17  "modified": []
18  /* ... */
19}

The pending and posted versions of a transaction may not necessarily share the same details: their name and amount may change. For example, the pending charge for a meal at a restaurant may not include a tip, but the posted version will include the final amount spent, including the tip. In some cases, a pending transaction may not convert to a posted transaction at all and will simply disappear; this can happen, for example, if the pending transaction was used as an "authorization hold," which is a sort of a deposit for a potential future transaction, frequently used by gas stations, hotels, and rental-car companies. Pending transactions are short-lived and frequently altered or removed by the institution before finally settling as a posted transaction.

Note that while transactions will rarely change once they have posted, a posted transaction cannot necessarily be considered immutable. For example, a refund or a recategorization of a transaction by the institution could cause a previously posted transaction to change. This is why it's important to apply all modified, added, and removed updates surfaced through /transactions/sync in order to maintain consistency with the underlying account data.

Example code in Plaid Pattern

For a real-life example, see update_transactions.js. This file demonstrates code for handling transaction states in the Node-based Plaid Pattern sample app.

Transaction state changes with /transactions/get

The content in this section and below applies only to existing integrations using the /transactions/get endpoint. It is recommended that any new integrations use /transactions/sync instead of /transactions/get, for easier and simpler handling of Transaction state changes.

Reconciling transactions

/transactions/get returns both pending and posted transactions; however, some institutions do not provide pending transaction data and will only supply posted transactions. The pending boolean field in the transaction indicates whether the transaction is pending or posted.

Plaid does not model the transition of a pending to posted transaction as a state change for an existing transaction; instead, the posted transaction is a new transaction with a pending_transaction_id field that matches it to a corresponding pending transaction. When a pending transaction is converted to a posted transaction, Plaid removes the pending transaction, sends a TRANSACTIONS_REMOVED webhook, and returns the new, posted transaction. The posted transaction will have a pending_transaction_id field whose value is the transaction_id of the now-removed pending transaction. The posted transaction’s date will reflect the date the transaction was posted, which may differ from the date on which the transaction actually occurred.

In some rare cases, Plaid will fail to match a posted transaction to its pending counterpart. On such occasions, the posted transaction will be returned without a pending_transaction_id field, and its pending transaction is removed.

Handling pending and posted transactions

To manage the movement of a transaction from pending to posted state, you will need to handle the TRANSACTIONS_REMOVED webhook to identify the removed transactions, then delete them from your records. For detailed instructions, see Transactions webhooks.

income

Introduction to Income

Verify income and paystubs with Income.

Explore API

Overview

Plaid Income (currently US and Canada only) helps you verify anyone's income and employment in seconds, facilitating an improved decisioning and underwriting process. Depending on the Income product you choose, you can request information such as pay stub data, income streams, and historical income. You can verify a user's income via three products:

Payroll Income: Retrieve income information, including the information available on a pay stub, from a user-connected payroll account. For an example of data returned, see the API Reference.

Payroll Income flow
Payroll Income Link flow

Document Income: Retrieve parsed income information via user-uploaded documents such as a pay stub, W-2, or 1099 form. For an example of data returned, see the API Reference.

Document Income flow
Document Income Link flow

Bank Income: Retrieve income information from a user-connected bank account. Data available includes a breakdown of income streams to the account, as well as recent and historical income. For an example of data returned, see the API Reference.

Bank Income flow
Bank Income Link flow

Income is configurable, allowing you to choose at the time of connection which income verification method best suits your user’s needs. The Document Income solution is a natural fallback to the Payroll Income solution, but you are also able to mix and match income verification methods.

For a fuller view of a borrower's financial situation, Income can also be used with Assets, which provides user-permissioned asset verification.

Depending on your use case, you may want to enable different income verification methods. If your use case relies on net income or income deposited in a user’s bank account, you can use Bank Income. If you plan to use other Plaid products, such as Auth and Balance for payments, or Assets for asset verification, Bank Income allows for a single Link experience, without requiring your user to go through multiple flows. For use cases that require gross income verification, you may want to use Payroll and/or Document Income.

MethodData sourceProcessing timeIncome supportedIntegrates w/other Plaid APIs
Bank IncomeUser logs in to bank accountInstantNet / gross (W2, self-employment, gig, multi-stream)Yes
Payroll IncomeUser logs in to payroll providerInstant~80% of US workforce (both W2 and gig)No
Document IncomeUser uploads W2 or pay stubs~15 minAny W2 or pay stub incomeNo
Prefer to learn by watching? Get an overview of how Income works in just 3 minutes!

Income integration process

  1. Call /user/create to create a user_token that will represent the end user interacting with your application. This step will only need to be done once per end user.
  2. (Optional) Call /credit/payroll_income/precheck with the user_token. This endpoint will indicate Plaid's confidence that a user will be able to complete the Payroll Income flow and can increase conversion by customizing the Payroll flow in Link for the specific user. For users where the endpoint returns a low confidence in their ability to connect via Payroll Income, we recommend you launch Link with either Document Income or Bank Income instead.
  3. Call /link/token/create. In addition to the required parameters, you will need to provide the following:
    • For user_token, provide the user_token from /user/create.
    • For products, use ["income_verification"]. If using Bank Income, you can also specify additional products, but note that it is not recommended to specify transactions along with income_verification; if you want to use Transactions with Bank Income, initialize Bank Income first. For more details, see Choosing when to initialize products.
    • For income_verification.income_source_types, use either payroll (for Payroll and Document Income) or bank (for Bank Income). If using Bank Income, you must also specify how many days of data to collect via income_verification.bank_income.days_requested. You can further customize the flows enabled and the amount of data collected via optional parameters; see the API Reference for more details.
    • Provide a webhook URI with the endpoint where you will receive Plaid webhooks.
    • If you collect income information directly from your users, provide it in the income_verification.stated_income_sources parameter. This data is used to improve the accuracy of data sent back to you, such as income stream categories.
  4. On the client side, create an instance of Link using the link_token returned by /link/token/create; for more details, see the Link documentation.
  5. Open Link in your web or mobile client and listen to the onSuccess and onExit callbacks, which will fire once the user has finished or exited the Link session.
    • If using Bank Income, call /credit/sessions/get in your server after receiving onSuccess, passing in the user_token from step 1.
      • If the user has finished the Bank Income verification flow, then the most recent session will have a bank_income_result with status APPROVED.
      • If you are using other Plaid products such as Auth or Balance alongside Bank Income, make sure to capture each public_token from the item_add_results array returned by /credit/sessions/get and exchange it for an access_token. For more details on token exchange flows, see the Token exchange flow.
      • If using a Multi-Item session, you will also need to call /credit/sessions/get after receiving the onExit callback; for more details, see Enabling Multi Item Sessions for Bank Income.
    • If using Payroll or Document Income, listen for the INCOME: INCOME_VERIFICATION webhook. For more details, see Income webhooks.
  6. (Optional, Document Income only) To retrieve document fraud signals as part of the Document Income flow, call /credit/payroll_income/risk_signals/get.
  7. To retrieve data, call the credit endpoints using the user_token.

Income webhooks

When using Payroll or Document Income, Plaid will asynchronously process the income data and send an INCOME: INCOME_VERIFICATION webhook once processing is complete. If processing was successful, the webhook's verification_status value will be VERIFICATION_STATUS_PROCESSING_COMPLETE. If you attempt to retrieve the income data before it has been processed, you may receive a 400 response with the error code PRODUCT_NOT_READY. Awaiting the webhook before calling /credit/payroll_income/get is strongly recommended.

Processing will usually complete within a few seconds if the user's income was verified via Payroll Income. If the user verified their income via Document Income, processing may take up to 45 minutes.

When using Bank Income, no webhooks are sent; data will be available immediately.

Testing Income

Income can be tested in Sandbox against test data without contacting Plaid. In order to test Income against live Items in either Development or Production, you will need to first request access by submitting a product access request Support ticket explaining your use case.

In the Sandbox environment, when testing Document Income, the contents of the actual document will not be processed and Sandbox will instead use pre-populated test data. This data will be available immediately. To test that your application properly handles the real-world delayed processing behavior of Document Income, test in the Development environment.

/credit/payroll_income/get can optionally be tested in Sandbox without using Link. Call /user/create, pass the returned user_token to /sandbox/public_token/create (ins_90 is a good sample institution_id for testing Income in Sandbox), and then call /credit/payroll_income/get. The output of /sandbox/public_token/create will not be used, but calling it initializes the user token for testing.

To test the /credit/payroll_income/precheck endpoint in Sandbox, use test employer objects with the employer names employer_good or employer_bad, to generate HIGH or LOW confidence scores. employer_multi can be used to generate a HIGH confidence score with multiple payroll options. Any other employer will result in an UNKNOWN confidence score. Likewise, use the test access tokens access_good or access_bad to generate HIGH or LOW confidence scores. Any other access token will result in an UNKNOWN confidence score.

Plaid provides a GitHub repo with test data for testing Income; make sure to update any test data in these files to be dated within the last 90 days before using this data in Sandbox. For more information on configuring custom Sandbox data, see Configuring the custom user account.

Testing Bank Income

To help you test Bank Income, Plaid provides a custom Sandbox user with Bank Income. To use the custom user, select a non-OAuth institution within Link and use username user_bank_income and password {}. This will provide up to two years of income data with various income categories and pay frequencies. Please note: the basic Sandbox credentials (user_good/pass_good) will not return data when used to test Bank Income.

If you’d like to test Bank Income with custom data, Plaid also provides a test JSON configuration object. To load this data into Sandbox, update the JSON object so that all transaction dates are within the date range requested and then copy and paste the JSON into the Sandbox Users pane in the Dashboard.

/credit/bank_income/get can optionally be tested in Sandbox without using Link. Call /user/create and pass the returned user_token to /sandbox/public_token/create. /sandbox/public_token/create must be called with the following request body:

1{
2  "client_id": "your-client-id-goes-here",
3  "secret": "your-sandbox-secret-goes-here",
4  "institution_id": "ins_20", //any valid institution id is fine
5  "initial_products": ["income_verification"],
6  "user_token": "user-token-goes-here", //use the user_token from the `/user/create` call made earlier
7  "options": {
8    "override_username": "user_bank_income",
9    "override_password": "{}",
10    "income_verification": {
11      "income_source_types": ["bank"],
12      "bank_income": {
13          "days_requested": 180 //any number of days under 730 is valid
14        }
15    }
16  },
17}

After calling /sandbox/public_token/create, call /credit/bank_income/get using the same user_token. The output of /sandbox/public_token/create will not be used, but calling it initializes the user token for testing.

Enabling multi-Item sessions for Bank Income

Many users get income deposited into multiple institutions. To help capture a user’s full income profile, you can allow your users to link multiple accounts within the same link session on web integrations.

Bank Income Multi Item flow
Bank Income Multi Item Link flow

To enable this flow, when calling /link/token/create set the bank_income.enable_multiple_items option to true.

After the user has exited Link and you receive an onSuccess or onExit callback, there will be a distinct item_add_result returned in the /credit/sessions/get response for each Item the user successfully linked. If the user has completed the Bank Income verification flow for a given Item, there will be a corresponding bank_income_result for that Item with status APPROVED. Ensure that you call /credit/sessions/get for both onSuccess and onExit Link callbacks, as the Link callback will only reflect the state of the last Item linked.

While you can access Bank Income data with the user_token, if you are planning to use these account connections for other Plaid products (such as Auth, Balance, etc.), make sure to exchange each public token found in the item_add_results for an access token, using /item/public_token/exchange.

Verifying Bank Income for existing Items

If your user has already connected their depository bank account to your application for a different product, you can add Bank Income to the existing Item via update mode.

To do so, in the /link/token/create request described above, populate the access_token field with the access token for the Item. If the user connected their account less than two years ago, they can bypass the Link credentials pane and complete just the Income Verification step. Otherwise, they will be prompted to complete the full Plaid Bank Income Link flow.

Fraud detection

To detect potential document fraud or document tampering during the Document Income flow, use the optional /credit/payroll_income/risk_signals/get endpoint. This endpoint is not enabled by default; to request access, contact support or your Plaid Account Manager.

Sample app code

For an example of an app that incorporates Income, see the React and NodeJS-based Income Sample app. This application uses Income and Liability data to help determine whether the user can qualify for financing on a pre-owned hoverboard. It supports the use of Payroll, Document, and Bank Income data.

Next steps

To learn more about Income endpoints, see the Income API Reference. For additional guidance and tips on implementing Income, you can also see the Plaid income verification solution guide.

If you're ready to launch to Production, see the Launch checklist.

auth

Introduction to Auth

Instantly retrieve account information to set up online payments via ACH and more.

Link an account
Fetch account info
Initiate a payment

Explore API

Auth allows you to request a user's checking or savings account information, making it easy for you to initiate credits or debits. For example, your app might allow users to accumulate a credit balance that they can cash out to a bank account, or it might allow users to pay you using their bank account information. With Auth, a user can provide this information in a frictionless way, simply by authenticating into their bank account.

Auth must be used with a third-party payment processor to move money: either a Plaid Partner or another third party. For more information, see Using a Payments Service. For an all-in-one solution that includes payment processor functionality, see Transfer (US-only).

Note that Auth can only be used with checking or savings accounts. Auth cannot be used with other depository accounts, such as money market accounts. Credit-type accounts, including credit cards, cannot receive payments directly via electronic interbank transfers, and Auth data cannot be used to set up credit card payments.

Prefer to learn by watching? Get an overview of how Auth works in just 3 minutes!

Enhancing Auth with related products

Auth is commonly used in combination with other Plaid APIs that reduce risk and support compliance.

For more information, see Balance (to verify accounts have sufficient funds), Signal (to calculate the risk of ACH returns with ML-powered analysis), and Identity (to verify ownership information on the account).

For account funding use cases, see Identity Verification for an end-to-end KYC compliance solution with optional AML capabilities.

Auth integration process

Below is a high level overview of the Auth integration process. For a more detailed walkthrough, see Add auth to your app or (if applicable) the docs for the specific partner you are using.

  1. Create a Link token by calling /link/token/create with auth in the products parameter. You may also set optional parameters here to extend coverage to more banks. For details, see Additional auth coverage. If you want to limit the user to linking only a single account, you can do so via a Link customization. For details, see Configuring Link with Auth.
  2. Initialize Link with the Link token from the previous step. Once the user has successfully completed the Link flow, exchange the public_token for an access_token. For more details, see Link.
  3. If using a Plaid partner for payment processing, ensure the partner is enabled on your Plaid Dashboard, then call /processor/token/create or /processor/stripe/bank_account_token/create to obtain a token that you will provide to the partner to enable funds transfers. For more detailed instructions, including a full walkthrough, see Auth payment partners.
  4. If not using a Plaid partner, call /auth/get to obtain the account and routing number, then provide these fields to your payment processing system.
  5. (Optional) To reduce fraud and complement know-your-customer processes, call /identity/get to verify that the identity information held by the bank matches the information that the user has provided to you. For more details, see Identity.
  6. (Optional) If you plan to transfer funds from the linked bank account, check the account's balance beforehand by calling /accounts/balance/get to avoid risk of an overdraft. For more details, see Balance.

Using a payments service

Looking for bank-to-bank transfer capabilities and don't have a payment processor yet? Check out Transfer (US only) for a money movement solution with built-in payment processing capabilities.

When using Auth, you will send Auth data to a payments service to initiate an interbank transfer; Plaid does not function as the payment processor. While Plaid is processor-agnostic and allows you to work with any partner you want, one easy way to make transfers is to work with a payments platform that partners with Plaid, such as Dwolla or Stripe. Working with these partners, you will not call the /auth/get endpoint, so you will not obtain a user's bank account information. Instead, you will call /processor/token/create or /processor/stripe/bank_account_token/create to obtain a Plaid token that you will provide to the partner and that allows them to make these Plaid API calls as needed. For detailed instructions on how to set up Auth with a Plaid partner, as well as a list of supported funds transfer partners, see Auth Partnerships.

If you choose to use a payments provider who is not a Plaid partner, you will need to obtain bank account numbers and codes using /auth/get. Given the sensitive nature of this information, we recommend that you consult the Open Finance Data Security Standard for security best practices. We also recommend that you do not store account numbers. You can integrate with one of Plaid's Data Security partners to process and share tokenized bank account numbers instead of raw bank account numbers. Contact your Account Manager to learn more about these partnerships.

Covering more institutions

When used in its default configuration, Auth provides access to approximately 90% of financial institution accounts in supported countries. In the US, Plaid also offers additional flows you can implement to cover more institutions with Auth. For more information, see Full Auth coverage.

Configuring Link with Auth

By default, only checking and savings accounts will appear when using Auth, and institutions that do not support these accounts will not appear in the Institution Select pane.

When using Auth, you will typically only need access to the one specific account that the end user wants to use to fund the payment, rather than all checking and savings accounts they may have at the same institution. Because of this, it is recommended to use the Account Select Link customization when configuring Link for use with Auth, to limit unnecessary access to user accounts. You can enable Account Select from the Dashboard.

Auth details by country

Just as there are multiple systems for bank codes and account numbers, there are also multiple systems for moving money from bank to bank. These systems are known as interbank transfer systems. The interbank transfer system used for an account depends on which country it is located in. Depending on the country, a bank account may participate in multiple interbank transfer systems and thus have multiple bank codes. For example, UK bank accounts participate in both SEPA and BACS payments. By calling /auth/get, you will receive all account numbers and bank codes associated with an Item.

United States (ACH)

In the United States, the bank code is known as a routing number, and the interbank transfer system is the Automated Clearing House (ACH) system. Because the ACH system can take several days to move money and can only be used within the United States, banks also have a second routing number, known as the wire transfer routing number, used to accept wire transfers. Wire transfers can be used to receive international payments and are faster than ACH transfers, but often involve a fee.

For a detailed, comprehensive guide to ACH transfers and payments, see Plaid's Modern Guide to ACH.

1"numbers": {
2  "ach": [
3    {
4      "account": "1111222233330000",
5      "account_id": "bWG9l1DNpdc8zDk3wBm9iMkW3p1mVWCVKVmJ6",
6      "routing": "011401533",
7      "wire_routing": "021000021"
8    }
9  ],
10  "bacs": [],
11  "eft": [],
12  "international": []
13}
Canada (EFT)

In Canada, the bank code is also known as a routing number, but it is in a different format than US routing numbers and broken into two pieces: the transit number (also known as the branch number), followed by the institution number. The interbank transfer system in Canada is the Electronic Funds Transfer (EFT) system.

1"numbers": {
2  "ach": [],
3  "bacs": [],
4  "eft": [
5    {
6      "account": "111122220000",
7      "account_id": "qVZ3Bwbo5wFmoVneZxMksBvN6vDad6idkndAB",
8      "branch": "01533",
9      "institution": "114"
10    }
11  ],
12  "international": []
13}
Europe (SEPA transfers)

In the European Economic Area member states (which includes Euro zone nations, as well as the United Kingdom), the bank code is called a Bank Identifier Code (BIC), also known as a SWIFT code. Each bank account has a number in a standard format, known as the International Bank Account Number (IBAN), which is used along with the BIC for funds transfers. Many bank accounts also have internal, non-IBAN account numbers that cannot be used for funds transfers. The funds transfer system is known as the Shared European Payment Area (SEPA), and it supports three types of funds transfers: SEPA credit transfer, SEPA instant credit transfer, and SEPA direct debit.

1"numbers": {
2  "ach": [],
3  "bacs": [],
4  "eft": [],
5  "international": [
6    {
7      "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
8      "bic": "IE64BOFI90583812345678",
9      "iban": "IE64BOFI90583812345678"
10    }
11  ]
12}
United Kingdom (BACS)

The UK uses the SEPA system as well as its own system, known as the Bankers Automated Clearing System (BACS), in which the bank code is known as a sort code. Similar to the ACH system, payments within the BACS system cannot be made outside the UK and take several days to process. BACS payments are typically used for recurring direct debit payments, such as payroll. UK bank accounts will typically have both a BACS sort code and an IBAN and support both BACS transfers and SEPA transfers.

1"numbers": {
2  "ach": [],
3  "bacs": [
4    {
5      "account": "80000000",
6      "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
7      "sort_code": "040004"
8    }
9  ],
10  "eft": [],
11  "international": [
12    {
13      "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
14      "bic": "MONZGB21XXX",
15      "iban": "GB23MONZ04000480000000"
16    }
17  ]
18}

For UK-based implementations, also consider the Payment Initiation API, which allows end-to-end payments directly, without having to integrate an additional payment processor.

Sample app code

For a real-life example of an app that incorporates Auth, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that fetches Auth data in order to set up funds transfers. The Auth code can be found in items.js.

Testing Auth

Plaid provides a GitHub repo with test data for testing Auth in Sandbox, helping you test configuration options beyond those offered by the default Sandbox user. For more information on configuring custom Sandbox data, see Configuring the custom user account.

For details on testing Auth with more complex Auth flows such as micro-deposit-based Auth, first familiarize yourself with Adding Institution Coverage, then see Test in Sandbox.

Next steps

Now that you understand Auth, add Auth to your app, or see Move Money with Auth partners to see specific instructions for configuring Auth with Plaid partners.

If you are using Auth as part of an account funding use case, see the Plaid Account Funding Guide for an overview of all required steps.

If you're ready to launch to Production, see the Launch checklist.

link android android v3 migration

2.x to 3.x Migration Guide

Reference for migrating the Link Android SDK from 2.x to 3.x

Summary of changes

Plaid released the Android 3.0.0 SDK on September 20th, 2020. Upgrading to the new 3.x SDK allows you to take advantage of a unified mobile API and support all new features. This article provides a guide on how to upgrade a Plaid integration from the Android 2.x SDK to the 3.x SDK.

Remove initialize

Select Language
1Plaid.initialize(this)

Is no longer part of the API and can be removed.

Opening Link

Creating Configuration
2.x.x3.x.x
com.plaid.link.configuration.LinkConfigurationcom.plaid.link.configuration.LinkPublicKeyConfiguration
LinkPublicKeyConfiguration.paymentTokenUse the LinkPublicKeyConfiguration.token field instead
com.plaid.link.configuration.AccountSubtypecom.plaid.link.result.LinkAccountSubtype
com.plaid.link.configuration.AccountTypecom.plaid.link.result.LinkAccountType
PlaidEnvironmentdeprecated
PlaidProductdeprecated
Select Language
1val linkTokenConfiguration = linkTokenConfiguration {
2  token = "LINK_TOKEN_FROM_SERVER"
3  logLevel = if (BuildConfig.DEBUG) LinkLogLevel.VERBOSE else LinkLogLevel.ERROR
4}
PlaidHandler

Create a PlaidHandler - A PlaidHandler is a one-time use object used to open a Link session. It should be created as early as possible, since it must be completed before Link opens, and if delayed until just before Link opening it can have a perceptible impact on Link startup time.

Select Language
1val plaidHandler: PlaidHandler = Plaid.create(application, linkTokenConfiguration)
Opening Link

We've removed the openLink functions on the Plaid object as well as the Kotlin extension functions for Activity and Fragment.

Select Language
1Plaid.openLink(activity, configuration)
1this@MyActivity.openPlaidLink(configuration)
1this@MyFragment.openPlaidLink(configuration)

Instead you will need to call open on the PlaidHandler you created, passing in an Activity or Fragment.

Select Language
1plaidHandler.open(activity)

Handling Results

LinkResultHandler

com.plaid.link.result.PlaidLinkResultHandler has been renamed to com.plaid.link.result.LinkResultHandler

LinkSuccessMetadata

LinkSuccessMetadata.rawMetadata renamed to LinkSuccessMetadata.metadata

LinkAccount

Fields renamed

  • accountId -> id
  • accountName -> name
  • accountNumber -> mask
  • accountSubtype -> subtype also type changed from String to com.plaid.link.result.LinkAccountSubtype
  • accountType has been removed, it is now a com.plaid.link.result.LinkAccountType object within LinkAccountSubtype
Select Language
1private val linkResultHandler = LinkResultHandler(
2  // ...
3  onSuccess = { it: LinkSuccess ->
4    // Send public_token to your server, exchange for access_token
5    val publicToken = it.publicToken
6    val metadata = it.metadata
7    metadata.accounts.forEach { account ->
8      val accountId = account.id
9      val accountName = account.name
10      val accountMask = account.mask
11      val accountSubType = account.subtype
12    }
13    val institutionId = metadata.institution?.id
14    val institutionName = metadata.institution?.name
15  }
16)
LinkError
  • errorCode has been typed as an ErrorCode object
  • errorType has been removed from LinkError and added to the ErrorCode object
  • errorJson field has been added with raw JSON from server
LinkExitMetadata
  • institutionId and institutionName moved into institution which is a LinkInstitution and renamed to id and name object
  • exitStatus removed
  • metadataJson field has been added with raw JSON from server
Select Language
1private val linkResultHandler = LinkResultHandler(
2  // ...
3  onExit = {
4    val error = it.error
5    error?.let { error ->
6      val errorCode = error.errorCode
7      val errorType = error.errorCode.errorType
8      val errorMessage = error.errorMessage
9      val displayMessage = error.displayMessage
10    }
11    val metadata = it.metadata
12    val institutionId = metadata.institution?.id
13    val institutionName = metadata.institution?.name
14    val linkSessionId = metadata.linkSessionId;
15    val requestId = metadata.requestId;
16  }
17)

Handling Events

LinkEventMetadata metadataJson added with raw JSON from server

Exceptions

All exceptions moved from com.plaid.link.internal.exceptions to com.plaid.link.exceptions

link account select v2 migration guide

Account Select v2 migration guide

How to migrate your application to Account Select v2

Introduction

Plaid has introduced an updated Account Select pane (Account Select v2). This improved experience gives users even more control over and transparency into the accounts they share with you and Plaid. When using Account Select v2, if a user links an Item at an institution where they hold more than one financial account, you will only receive data from the specific accounts the user has selected to share with you. When a user doesn't select a certain account on this pane, data associated with that account is not shared with you.

This guide covers the client and server-side changes required to implement the updated Account Select pane.

Account Select v2 is mandatory for all Plaid implementations. Any implementation not migrated by March 2022 was automatically migrated at that time. Beginning in April 2023, existing Items at OAuth-enabled institutions that are not currently on Account Select v2 will be converted to use Account Select v2 when sent through update mode.

What's new
  1. The API will only return data for the accounts the user has selected for Items created with Account Select v2 enabled (existing Items will not be affected). The Account Select pane can be configured to the "Enabled for one account", "Enabled for multiple accounts", or "Enabled for all accounts" behavior.
  2. A new NEW_ACCOUNTS_AVAILABLE webhook is available to notify you when a user may have a new account available to connect. To request a new account from a user, you can use Link in update mode.

Migration overview

  1. Review the implementation considerations.
  2. Update each of your Link customizations to Account Select v2
  3. (Optional) Listen for the new NEW_ACCOUNTS_AVAILABLE webhook and integrate update mode with Account Select enabled.
  4. Disable Account Select v1

Implementation considerations

Account Select v2 only returns data for accounts the user has selected. If your app currently depends on having access to all accounts associated with an Item as well as all future new accounts going forward (e.g. some personal financial management apps), we recommend making the following implementation changes:

  1. Configure Account Selection V2 with the "Enabled for all accounts" behavior, so that the pane automatically requires access to all accounts.
  2. If you’re using the NEW_ACCOUNTS_AVAILABLE webhook to prompt users to link additional accounts, you might want to provide context explaining why the user is being prompted to proceed through update mode.
  3. If you have built your own account management feature where users can link additional accounts directly from your app without having to go through update mode, you might want to update the in-app copy to clarify that the user will need to proceed through Link in order to add new accounts. You will also need to configure this feature to initiate update mode with Account Select enabled.

Update Link customizations

To opt into Account Select v2, go to your Link customization or create a new one (you may duplicate an existing customization by using the duplicate feature), click on the Version 2.0 tab, and select one of the new view behaviors:

  • Enabled for one account
  • Enabled for multiple accounts
  • Enabled for all accounts

Once you’ve selected a Version 2.0 View Behavior, click Publish. Your changes will go into effect the next time you initialize Link with this customization. Only newly created Items created with the updated customization will have the new API behavior; existing Items will not be affected.

If you want to downgrade to the previous experience, you can do so until March 2022 by clicking the Version 1.0 tab and clicking Publish. After March 2022 Account Select v1 will automatically be updated to Account Select v2. See automatic migration for more details.

We recommend that if you’re currently using the Account Select pane, you maintain the existing view behavior when you migrate to Account Select v2. If you haven’t used the Account Select pane before, you may want to consider the following:

  • If your Plaid use case is banking, consumer payments, or wealth, we recommend that you use the "Enabled for one account" or the "Enabled for multiple accounts" view behavior.
  • If your Plaid use case is personal financial management or lending, you may prefer to use the "enabled for all accounts" view behavior.

If you select the "Enabled for all accounts" configuration and a user selects an OAuth institution that manages their own account selection, Link will show guidance on the OAuth Pane for the user to "Share all accounts" before the user is redirected to the institution’s OAuth flow to continue the linking process.

Requesting data for new accounts

Plaid will issue webhooks to you whenever we discover new accounts for your user. You can find out about these new accounts by listening for the NEW_ACCOUNTS_AVAILABLE webhook.

To add these new accounts, initialize Link for update mode. Your call to /link/token/create must include the following:

  1. The update.account_selection_enabled flag set to true. To ensure you are able to use this flag, check that your Plaid library meets the minimum version required.
  2. A link_customization_name for a customization that enables Account Select v2. The settings on this customization will determine which View Behavior for the Account Select pane is shown in update flow. You may omit this parameter if your default customization has Account Select v2 enabled.
  3. (Optional) Any account_filters to specify account filtering. Note that this field cannot be set for update mode if account selection is not enabled.
1curl -X POST https://sandbox.plaid.com/link/token/create \
2-H 'Content-Type: application/json' \
3-d '{
4  "client_id": "CLIENT_ID",
5  "secret": "SECRET",
6  "client_name": "My App",
7  "user": { "client_user_id": "UNIQUE_USER_ID" },
8  "country_codes": ["US"],
9  "language": "en",
10  "webhook": "https://webhook.sample.com",
11  "access_token": "ENTER_YOUR_ACCESS_TOKEN",
12  "link_customization_name": "account_selection_v2_customization",
13  "update": { "account_selection_enabled": true }
14}'

Once your user has updated their account selection, all selected accounts will be shared in the accounts field in the onSuccess() callback from Link.

1const onSuccess = useCallback<PlaidLinkOnSuccess>(
2 (public_token: string, metadata: PlaidLinkOnSuccessMetadata) => {
3   // updated selected account ids
4   const account_ids = metadata.accounts.map(account => account.id);
5   // ...
6 },
7 [],
8);

Any de-selected accounts will no longer be shared with you. You will only receive data for accounts the user selects in update mode going forward.

We recommend that you remove any data associated with accounts your user has de-selected.

Transactions for new accounts

If the consumer shares new accounts for an Item initialized with the Transactions product, Plaid will send a TRANSACTIONS: INITIAL_UPDATE webhook and a TRANSACTIONS: HISTORICAL_UPDATE webhook when the initial and historical transaction updates complete for the new account selections.

Testing in Sandbox

You can test Account Select v2 in Sandbox by creating a Link customization with Account Select v2 enabled specifically for testing and initializing Link with that customization in the Sandbox environment. This will not impact production traffic.

To verify that you’re correctly handling the NEW_ACCOUNTS_AVAILABLE webhook, you can use the /sandbox/item/fire_webhook endpoint or you can use custom Sandbox data to trigger a change in accounts that will cause the webhook to fire:

  1. Create an Item in Link with Account Select v2 with the following configuration object:

    1{
    2  "override_accounts": [
    3    {
    4      "type": "depository",
    5      "subtype": "checking"
    6    }
    7  ]
    8}

Make sure that you have obtained an access_token corresponding to the configuration object before proceeding to the next step.

  1. Update the Item by changing the configuration object to add another account:

    1{
    2  "override_accounts": [
    3    {
    4      "type": "depository",
    5      "subtype": "checking"
    6    },
    7    {
    8      "type": "depository",
    9      "subtype": "savings"
    10    },
    11  ]
    12}

  2. The NEW_ACCOUNTS_AVAILABLE webhook should fire when Plaid runs its next periodic check for account updates, typically within 6 to 24 hours. Or, to force the check to occur immediately, you can go through the update mode flow for the Item.

Disabling Account Select v1

Once you have migrated each of your customizations to Account Select v2, go to the Migrations page in Team Settings and click Migrate.

This will remove the Version 1.0 tab from the Account Select customization options. Going forward, all new customizations will be created with the Account Select pane’s behavior set to "Enabled for multiple accounts" by default.

Automatic migration

If you did not migrate to Account Select v2 by March 2022, Plaid automatically migrated all of your customizations to Account Select v2, using the following rules:

  • If your customization has disabled Account Select v1, we defaulted you to the "Enabled for all accounts" Account Select v2 view behavior.
  • If your customization has enabled single select Account Select v1, we defaulted you to the "Enabled for one account select" Account Select v2 view behavior.
  • If your customization has enabled multi select Account Select v1, we defaulted you to the "Enabled for multiple accounts" Account Select v2 view behavior.

Minimum version for account select update mode

virtual accounts add to app

Add Virtual Accounts to your app

Use virtual accounts to gain additional insight and control over the flow of funds

In this guide, we'll walk through how to set up and manage virtual accounts. After integrating you will be able to send and receive money, make withdrawals and refunds, and reconcile funds for faster reconciliation.

Note: The Sandbox environment uses test data and does not interact with financial institutions.

Integrate with Plaid Payment Initiation and enable Virtual Accounts

Virtual accounts are designed to be used in conjunction with the Payment Initiation APIs. To get the most out of Plaid virtual accounts, first add Payment Initiation to your app. In order to be enabled for Virtual Accounts in Production, contact your Account Manager. To test in Sandbox, begin by creating a virtual account via /wallet/create.

Select Language
1const request: WalletCreateRequest = {
2  iso_currency_code: isoCurrencyCode,
3};
4try {
5  const response = await plaidClient.walletCreate(request);
6  const walletID = response.data.wallet_id;
7  const balance = response.data.balance;
8  const numbers = response.data.numbers;
9  const recipientID = response.data.recipient_id;
10} catch (error) {
11  // handle error
12}

Enable Virtual Account Transaction webhooks

Enable virtual account webhooks to receive notifications when new transaction events occur. Plaid will send a webhook for each transaction event. These notifications can be used to stay updated on transaction status information.

Funding your Virtual Account through Payment Initiation

Create a Payment that will be initiated to your virtual account
Select Language
1const request: PaymentInitiationPaymentCreateRequest = {
2  recipient_id: recipientID,
3  reference: 'TestPayment',
4  amount: {
5    currency: 'GBP',
6    value: 100.0,
7  },
8};
9try {
10  const response = await plaidClient.paymentInitiationPaymentCreate(request);
11  const paymentID = response.data.payment_id;
12  const status = response.data.status;
13} catch (error) {
14  // handle error
15}

Use the recipient_id associated with your wallet_id so Plaid knows to route the payment to your virtual account.

Launch and complete the Payment Initiation flow in Link

For more details on how to do this, see the Payment Initiation documentation.

Confirm that the payment has settled via a payment webhook

For more details, see the PAYMENT_STATUS_UPDATE webhook.

1{
2  "webhook_type": "PAYMENT_INITIATION",
3  "webhook_code": "PAYMENT_STATUS_UPDATE",
4  "payment_id": "<PAYMENT_ID>",
5  "new_payment_status": "PAYMENT_STATUS_SETTLED",
6  "old_payment_status": "PAYMENT_STATUS_EXECUTED",
7  "original_reference": "Account Funding 99744",
8  "adjusted_reference": "Account Funding 99",
9  "original_start_date": "2017-09-14",
10  "adjusted_start_date": "2017-09-15",
11  "timestamp": "2017-09-14T14:42:19.350Z"
12}
Confirm that funds have arrived in your virtual account via a transaction webhook

For more details, see the WALLET_TRANSACTION_STATUS_UPDATE webhook.

1{
2  "webhook_type": "WALLET",
3  "webhook_code": "WALLET_TRANSACTION_STATUS_UPDATE",
4  "wallet_id": "<WALLET_ID>",
5  "new_status": "SETTLED",
6  "old_status": "INITIATED",
7  "timestamp": "2021-09-14T14:42:19.350Z"
8}

Executing a Payout

Fetch your virtual account to confirm it has sufficient balance
Select Language
1const request: WalletGetRequest = {
2  wallet_id: walletID,
3};
4try {
5  const response = await plaidClient.walletGet(request);
6  const walletID = response.data.wallet_id;
7  const balance = response.data.balance;
8  const numbers = response.data.numbers;
9} catch (error) {
10  // handle error
11}
Execute a payout
Select Language
1const request: WalletTransactionExecuteRequest = {
2  wallet_id: walletID,
3  counterparty: {
4    name: 'Test',
5    numbers: {
6      bacs: {
7        account: '12345678',
8        sort_code: '123456',
9      },
10    },
11  },
12  amount: {
13    value: 1,
14    iso_currency_code: 'GBP',
15  },
16  reference: 'transaction ABC123',
17  idempotency_key: '39fae5f2-b2b4-48b6-a363-5328995b2753',
18};
19try {
20  const response = await plaidClient.walletTransactionExecute(request);
21  const transactionID = response.data.transaction_id;
22  const status = response.data.status;
23} catch (error) {
24  // handle error
25}
Confirm the payout was executed, via a transaction webhook

For more details, see the WALLET_TRANSACTION_STATUS_UPDATE webhook.

1{
2  "webhook_type": "WALLET",
3  "webhook_code": "WALLET_TRANSACTION_STATUS_UPDATE",
4  "wallet_id": "<WALLET_ID>",
5  "new_status": "EXECUTED",
6  "old_status": "INITIATED",
7  "timestamp": "2021-09-14T14:42:19.350Z"
8}

Refunding a Payment Initiation payment

Fetch your virtual account to confirm it has sufficient balance
Select Language
1const request: WalletGetRequest = {
2  wallet_id: walletID,
3};
4try {
5  const response = await plaidClient.walletGet(request);
6  const walletID = response.data.wallet_id;
7  const balance = response.data.balance;
8  const numbers = response.data.numbers;
9} catch (error) {
10  // handle error
11}
Refund a Payment Initiation payment
Select Language
1const request: PaymentInitiationPaymentReverseRequest = {
2  payment_id: paymentID,
3  reference: 'Refund for purchase ABC123',
4  idempotency_key: 'ae009325-df8d-4f52-b1e0-53ff26c23912',
5};
6try {
7  const response = await plaidClient.paymentInitiationPaymentReverse(request);
8  const refundID = response.data.refund_id;
9  const status = response.data.status;
10} catch (error) {
11  // handle error
12}
Confirm the refund was executed, via a transaction webhook

For more details, see the WALLET_TRANSACTION_STATUS_UPDATE webhook.

1{
2  "webhook_type": "WALLET",
3  "webhook_code": "WALLET_TRANSACTION_STATUS_UPDATE",
4  "wallet_id": "<WALLET_ID>",
5  "new_status": "EXECUTED",
6  "old_status": "INITIATED",
7  "timestamp": "2021-09-14T14:42:19.350Z"
8}

Next steps

If you're ready to launch to Production, see the Launch checklist.

auth partnerships astra

Add Astra to your app

Use Astra with Plaid Auth to send and receive payments!

Partnership Astra logo

Overview

Plaid and Astra have partnered to help businesses offer automated ACH transfers to their users. Using Plaid’s Auth product in tandem with the Astra automation platform gives fintech developers the ability to build advanced self-driving product experiences and enable programmatic money movement for their customers.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Astra account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Astra processor_token, which allows you to quickly and securely verify a bank funding source via Astra's API without having to store any sensitive banking information. Utilizing Plaid + Astra enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Astra in order to use the Plaid + Astra integration. You'll also need to enable your Plaid account for the Astra integration.

First, you will need to work with the Astra team to sign up for a Astra account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Astra to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Astra processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Astra, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Astra processor_token. You'll send this token to Astra and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Astra processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'astra',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Astra Production credentials prior to initiating live payment transactions in the Astra API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

transfer ach

ACH requirements

Learn about ACH requirements for Transfer, including processing windows, messaging requirements, and ACH returns

Overview

All payments initiated via Transfers are sent via ACH, which is a financial network for interbank electronic payments and money transfers in the US. ACH uses bank account details (account and routing numbers) to facilitate bank-to-bank transfers. The organization that governs ACH is known as Nacha.

This article outlines ACH details you will need to know for your Transfers implementation: Nacha requirements for providing messaging to your end users, processing windows and cutoffs for initiating ACH transfers, and how to handle ACH returns.

ACH authorization requirements

In accordance with Nacha Rules, you must obtain appropriate authorization from the owner of the bank account before initiating an ACH payment via Transfer. As the Originator of the transaction, it is your sole responsibility to (1) verify the identity of your customer; (2) determine their eligibility to purchase your products or services; and (3) obtain appropriate authorization to initiate ACH debits from or ACH credits to their account.

We recommend that you both follow the steps below and store information (such as user flow screenshots and activity logs) showing that you have done so. This information should be stored (in physical or digital format) for at least 2 years since the most recent authorized payment made by a customer. Note that the guidance given here is general; refer to the Nacha Rules to ensure you are complying with your obligations.

  1. Customer consent – Provide an authorization page that clearly states you are obtaining the customer’s consent to debit their bank account for a particular transaction or for recurring transactions.

  2. Transaction-specific information – Collect the date and time of the transaction, account information of debited account, item or service purchased, frequency of payment (if recurring), and IP address.

  3. Customer account information – Collect the name on the account, shipping details (if applicable), and any other ways to verify the customer’s identity.

  4. Transaction receipt – Provide the customer a receipt of the transaction by sending them an e-mail receipt of the transaction and also giving them the ability to print the authorization to retain a copy.

  5. Process to revoke authorization – Include a telephone number and e-mail address where your customer can contact you to do so, which should be on the authorization page and in the receipt.

Plaid Transfer UI provides out-of-the-box authorization language and a payments UX designed in accordance with the applicable authorization rules. The UX integrates seamlessly with Plaid Link, so you won't need to stand up any additional pages in your website or app. For more information, see Transfers using Transfer UI.

ACH processing windows

Transfers that are submitted via the /transfer/create endpoint will be submitted in the next processing window. For a same-day transfer, the cutoff time is 3:30PM Eastern Time. For a next-day transfer, the cutoff time is 5:30PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time to guarantee that it will be processed before the cutoff.

Note that same-day transfers submitted after 3:30PM Eastern Time and before 5:30PM Eastern Time will be automatically updated to be next-day and submitted to the network in that following ACH processing window. This update also applies to the sweep. This process minimizes the risk of return due to insufficient funds by reducing the delay between Plaid's balance check and the submission of the transfer to the ACH network. The settlement time remains the same as it would have been if the transfer had been submitted in next same-day window.

ACH processing windows are active only on banking days. Transfers will not be submitted to the network on weekends or bank holidays. Keep this in mind when creating transfers over weekends or on bank holidays. To mitigate, wait until the next banking day and then authorize and create the transfer.

Some accounts are subject to ACH processing hold times in order to reduce risk. If your account is subject to a hold, your Account Manager will inform you. Any hold will take place in between when funds are swept and the credit or debit to the consumer's account.

ACH returns

After a payment has been posted, a payment can be returned and clawed back from your account for a multitude of reasons. For example, a bank could determine that there are insufficient funds to complete the transfer, or a consumer can contact their bank and flag the transaction as unauthorized. If a transfer results in an ACH return, the funds will be automatically clawed back. In the event of an ACH return, we suggest you message the reversal to your user.

For a full list of all ACH return codes you may encounter, see ACH return codes.

Most common ACH return codes
R01 - Insufficient funds

This occurs if there are insufficient funds in the account. This return code is highly mitigated by the Transfer authorization engine, but you may see this return code if the authorization engine returns permitted and you still create the transfer. See Transfer decision authorization for more information.

If you are submitting the transfer on a Friday, we recommend using same-day ACH to decrease the likelihood of the user’s account balance dipping below the transfer amount over the weekend.

If you encounter an R01 return code, you can resubmit the payment.

R03 - No account or unable to locate account

This can occur for one of the following reasons:

This could happen if the user closed the account in the time between linking their account and creation of the transfer.

If you encounter an R03 return code, prompt the user to link another account via Plaid Link and use this newly linked account to create the transfer.

R10 - Customer advises not authorized

This can occur if the customer advises their bank that the payment you initiated is unauthorized. According to Nacha rules, these occurrences must be kept below 50 basis points.

Make sure you add proper web debit authorization language (for best practices, see ACH authorization requirements) to your "pay with bank" UX to protect against exposure of returns of over 60 days. If you don’t have proper web debit authorization language, you are exposed to returns of up to 1 year.

Unlike other ACH return codes, you cannot resubmit a payment after encountering an R10 error.

ACH return timing

Each ACH return code has a maximum window of time during which funds can be clawed back. For example, for some ACH return codes, the window of time is two banking days. The following is to give you a general idea of when returns typically occur, regardless of the specific ACH return code:

  • 50% of ACH returns occur by day 2 of submitting to the Nacha network
  • 90% of ACH returns occur by day 4 of submitting to the Nacha network
  • 95% of ACH returns occur by day 5 of submitting to the Nacha network
  • 99% of ACH returns occur by day 8 of submitting to the Nacha network

auth partnerships circle

Add Circle to your app

Use Circle with Plaid Auth to send and receive payments!

Partnership Circle logo

Overview

Learn how to integrate with Circle APIs to accept payments that settle in digital dollar stablecoins, and power your next generation internet commerce or marketplace with fast, cheap and global settlement technology.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Circle account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Circle processor_token, which allows you to quickly and securely verify a bank funding source via Circle's API without having to store any sensitive banking information. Utilizing Plaid + Circle enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Circle in order to use the Plaid + Circle integration. You'll also need to enable your Plaid account for the Circle integration.

First, you will need to work with the Circle team to sign up for a Circle account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Circle to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Circle processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Circle, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Circle processor_token. You'll send this token to Circle and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Circle processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'circle',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Circle Production credentials prior to initiating live payment transactions in the Circle API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

auth coverage same day link best practices

Same Day Micro-deposits Link best practices

Optimally configure Same Day Micro-deposits for your use case

Minimizing fraud with Same Day Micro-deposits

Maximize use of Plaid's fraud prevention solutions

Plaid provides a suite of fraud prevention products that assist your application in catching bad actors and ACH returns. Verifying the source of funds with Identity, confirming the real-time Balance prior to a transfer, and leveraging our machine learning model Signal to prevent returns and release funds earlier all require a credential-based connection to a user’s bank account. If an account is connected via Same Day Micro-deposits, these features are not available and could increase the likelihood that you experience fraud and ACH returns.

One way to enable Same-day Micro-deposits while reducing risk is to enable Reroute to Credentials. Reroute to Credentials is designed to redirect users to connect through the credential-based flows that enable fraud prevention products, while still allowing users to connect accounts that are not yet supported natively by Plaid. For more details, see Reroute to Credentials.

Configuring Auth Type Select as an active choice was shown in experiments to decrease overall conversion and increase the number of Same Day Micro-deposits accounts compared to configuring it as an option at Link failure points. If confirming the ownership on the account and return prevention are more important to your business than extended Auth coverage, we do not recommend configuring Same Day Micro-deposits as an option for consumers.

Adjust a user’s Link experience based on their risk profile

In order to reduce fraud upstream on your application, we recommend leveraging Plaid Identity Verification to verify a government ID or match with a selfie of the document holder. This requires your user to take additional steps, though ensures verification of the Identity before the user opts to link their bank account, and is available for all Auth Types (manual and credential-based).

If your application does not have an identity verification solution or Plaid Link is not gated from the general public with fraud prevention and user verification checks in place, we do not recommend adopting Same Day Micro-deposits as it may introduce an unnecessary fraud vector onto your platform.

If you identify a user to be riskier, consider disabling Same Day Micro-deposits (either as an optional configuration at Link failure points, or via the upfront Auth Type Select configuration) for those users, since fraud prevention products are not available when they connect via this method. To do this, set the same_day_microdeposits_enabled and/or auth_type_select_enabled parameters to false in the auth object in your /link/token/create call for that user.

Another option for riskier users is to leave Same Day Micro-deposits enabled, but enable Reroute to Credentials in Forced mode, which will only allow the user to link via Same Day Micro-deposits when using a routing number not supported by other authentication methods. To do this on a per-session basis, specify the FORCED value for the reroute_to_credentials field within the auth object in your /link/token/create call.

You may also consider changing your user’s experience with your service based on their connection method. For example, if a user connected via Same Day Micro-deposits, you may consider enforcing a lower transfer threshold than for users where it was possible to verify identity and increasing hold times on those funds.

Maximizing conversion

Adding institution coverage

Instant Match and Automated micro-deposits are supported as additional Auth types when Instant Auth is not available. Same Day Micro-deposits can be configured as an option at Link failure points. These configurations can improve conversion by enabling more users to connect their institutions when Instant Auth fails.

To optimize conversion, we strongly recommend sending your user a notification (e.g. email, SMS, push notification) prompting them to come back into your app and verify the micro-deposit code in the transaction description.

investments add to app

Add Investments to your app

Learn how to add Investments endpoints to your application

In this guide, we'll start from scratch and walk through how to use Investments to retrieve information on securities and holdings. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, you can skip ahead to Fetching investment data.

Get Plaid API keys and complete application and company profile

If you don't already have one, you'll need to create a Plaid developer account. After creating your account, you can find your API keys under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your application profile and company profile on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the Plaid Portal. Your application profile and company profile must be completed before connecting to certain institutions in Production.

Install and initialize Plaid libraries

You can use our official server-side client libraries to connect to the Plaid API from your application:

Select group for content switcher
Select Language
1// Install via npm
2npm install --save plaid

After you've installed Plaid's client libraries, you can initialize them by passing in your client_id, secret, and the environment you wish to connect to (Sandbox, Development, or Production). This will make sure the client libraries pass along your client_id and secret with each request, and you won't need to explicitly include them in any other calls.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can obtain from the Dashboard. These code samples also demonstrate starting up a server commonly used in each framework (such as Express or Flask).

Select group for content switcher
Select Language
1// Using Express
2const express = require('express');
3const app = express();
4app.use(express.json());
5
6const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
7
8const configuration = new Configuration({
9  basePath: PlaidEnvironments.sandbox,
10  baseOptions: {
11    headers: {
12      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
13      'PLAID-SECRET': process.env.PLAID_SECRET,
14    },
15  },
16});
17
18const client = new PlaidApi(configuration);

Create an Item in Link

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the Link documentation.

Using Link, we will create a Plaid Item, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. If you want to customize Link's look and feel, you can do so from the Dashboard.

Before initializing Link, you will need to create a new link_token on the server side of your application. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the /link/token/create endpoint. Then, on the client side of your application, you'll need to initialize Link with the link_token that you just created.

Create a link_token
Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Install Link dependency
Select Language
1<head>
2  <title>Connect a bank</title>
3  <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
4</head>
Configure the client-side Link handler
1const linkHandler = Plaid.create({
2  token: (await $.post('/create_link_token')).link_token,
3  onSuccess: (public_token, metadata) => {
4    // Send the public_token to your app server.
5    $.post('/exchange_public_token', {
6      public_token: public_token,
7    });
8  },
9  onExit: (err, metadata) => {
10    // Optionally capture when your user exited the Link flow.
11    // Storing this information can be helpful for support.
12  },
13  onEvent: (eventName, metadata) => {
14    // Optionally capture Link flow events, streamed through
15    // this callback as your users connect an Item to Plaid.
16  },
17});
18
19linkHandler.open();

Get a persistent access_token

Next, on the server side, we need to exchange our public_token for an access_token and item_id. The access_token will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the /item/public_token/exchange endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the access_token and item_id in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. The access_token will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via /item/remove. The access_token should be stored securely, and never in client-side code. A public_token is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

Select group for content switcher
Select Language
1app.post('/api/exchange_public_token', async function (
2  request,
3  response,
4  next,
5) {
6  const publicToken = request.body.public_token;
7  try {
8    const response = await client.itemPublicTokenExchange({
9      public_token: publicToken,
10    });
11
12    // These values should be saved to a persistent database and
13    // associated with the currently signed-in user
14    const accessToken = response.data.access_token;
15    const itemID = response.data.item_id;
16
17    res.json({ public_token_exchange: 'complete' });
18  } catch (error) {
19    // handle error
20  }
21});

Fetching investment data

Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API. Once you've retrieved investment data for an account, you can then use it to analyze data such as trading activity, net worth, and asset allocations.

Investments endpoints return two primary pieces of information about the investment account. The first is details on the holding itself (if using /investments/holdings/get) or the transaction (if using /investments/transactions/get). The second is details about the security itself. Each security, transaction, and holding contains a security_id field, which functions as a key for cross-referencing the holding or transaction with the security it pertains to. For more detailed information on the schema for information returned, see /investments/holdings/get or /investments/transactions/get.

Investments data is typically updated daily, after market close. To be alerted when new data is available to be retrieved, listen to Investments webhooks.

Fetching investment holdings
Select group for content switcher
Select Language
1const { InvestmentsHoldingsGetRequest } = require('plaid');
2
3// Pull Holdings for an Item
4const request: InvestmentsHoldingsGetRequest = {
5  access_token: accessToken,
6};
7try {
8  const response = await plaidClient.investmentsHoldingsGet(request);
9  const holdings = response.data.holdings;
10  const securities = response.data.securities;
11} catch (error) {
12  // handle error
13}

Example response data is below.

1{
2  "accounts": [
3    {
4      "account_id": "5Bvpj4QknlhVWk7GygpwfVKdd133GoCxB814g",
5      "balances": {
6        "available": 43200,
7        "current": 43200,
8        "iso_currency_code": "USD",
9        "limit": null,
10        "unofficial_currency_code": null
11      },
12      "mask": "4444",
13      "name": "Plaid Money Market",
14      "official_name": "Plaid Platinum Standard 1.85% Interest Money Market",
15      "subtype": "money market",
16      "type": "depository"
17    },
18    {
19      "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
20      "balances": {
21        "available": null,
22        "current": 320.76,
23        "iso_currency_code": "USD",
24        "limit": null,
25        "unofficial_currency_code": null
26      },
27      "mask": "5555",
28      "name": "Plaid IRA",
29      "official_name": null,
30      "subtype": "ira",
31      "type": "investment"
32    },
33    {
34      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
35      "balances": {
36        "available": null,
37        "current": 23631.9805,
38        "iso_currency_code": "USD",
39        "limit": null,
40        "unofficial_currency_code": null
41      },
42      "mask": "6666",
43      "name": "Plaid 401k",
44      "official_name": null,
45      "subtype": "401k",
46      "type": "investment"
47    }
48  ],
49  "holdings": [
50    {
51      "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
52      "cost_basis": 0.01,
53      "institution_price": 0.011,
54      "institution_price_as_of": null,
55      "institution_value": 110,
56      "iso_currency_code": "USD",
57      "quantity": 10000,
58      "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
59      "unofficial_currency_code": null
60    },
61    {
62      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
63      "cost_basis": 23,
64      "institution_price": 27,
65      "institution_price_as_of": null,
66      "institution_value": 636.309,
67      "iso_currency_code": "USD",
68      "quantity": 23.567,
69      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
70      "unofficial_currency_code": null
71    }
72  ],
73  "item": {
74    "available_products": [
75      "balance",
76      "credit_details",
77      "identity",
78      "investments",
79      "liabilities",
80      "transactions"
81    ],
82    "billed_products": ["assets", "auth", "investments"],
83    "consent_expiration_time": null,
84    "error": null,
85    "institution_id": "ins_3",
86    "item_id": "4z9LPae1nRHWy8pvg9jrsgbRP4ZNQvIdbLq7g",
87    "webhook": "https://www.genericwebhookurl.com/webhook"
88  },
89  "request_id": "l68wb8zpS0hqmsJ",
90  "securities": [
91    {
92      "close_price": 0.011,
93      "close_price_as_of": null,
94      "cusip": null,
95      "institution_id": null,
96      "institution_security_id": null,
97      "is_cash_equivalent": false,
98      "isin": null,
99      "iso_currency_code": "USD",
100      "name": "Nflx Feb 01'18 $355 Call",
101      "proxy_security_id": null,
102      "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
103      "sedol": null,
104      "ticker_symbol": "NFLX180201C00355000",
105      "type": "derivative",
106      "unofficial_currency_code": null
107    },
108    {
109      "close_price": 27,
110      "close_price_as_of": null,
111      "cusip": "577130834",
112      "institution_id": null,
113      "institution_security_id": null,
114      "is_cash_equivalent": false,
115      "isin": "US5771308344",
116      "iso_currency_code": "USD",
117      "name": "Matthews Pacific Tiger Fund Insti Class",
118      "proxy_security_id": null,
119      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
120      "sedol": null,
121      "ticker_symbol": "MIPTX",
122      "type": "mutual fund",
123      "unofficial_currency_code": null
124    }
125  ]
126}
Fetching investment transactions
Select group for content switcher
Select Language
1const request: InvestmentsTransactionsGetRequest = {
2  access_token: accessToken,
3  start_date: '2019-01-01',
4  end_date: '2019-06-10',
5  options: {
6    count: 250,
7    offset: 0,
8  },
9};
10try {
11  const response = await plaidClient.investmentsTransactionsGet(request);
12  const investmentTransactions = response.data.investment_transactions;
13} catch (error) {
14  // handle error
15}

Sample response data is below.

1{
2  "accounts": [
3    {
4      "account_id": "5e66Dl6jNatx3nXPGwZ7UkJed4z6KBcZA4Rbe",
5      "balances": {
6        "available": 100,
7        "current": 110,
8        "iso_currency_code": "USD",
9        "limit": null,
10        "unofficial_currency_code": null
11      },
12      "mask": "0000",
13      "name": "Plaid Checking",
14      "official_name": "Plaid Gold Standard 0% Interest Checking",
15      "subtype": "checking",
16      "type": "depository"
17    },
18    {
19      "account_id": "KqZZMoZmBWHJlz7yKaZjHZb78VNpaxfVa7e5z",
20      "balances": {
21        "available": null,
22        "current": 320.76,
23        "iso_currency_code": "USD",
24        "limit": null,
25        "unofficial_currency_code": null
26      },
27      "mask": "5555",
28      "name": "Plaid IRA",
29      "official_name": null,
30      "subtype": "ira",
31      "type": "investment"
32    },
33    {
34      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
35      "balances": {
36        "available": null,
37        "current": 23631.9805,
38        "iso_currency_code": "USD",
39        "limit": null,
40        "unofficial_currency_code": null
41      },
42      "mask": "6666",
43      "name": "Plaid 401k",
44      "official_name": null,
45      "subtype": "401k",
46      "type": "investment"
47    }
48  ],
49  "investment_transactions": [
50    {
51      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
52      "amount": -8.72,
53      "cancel_transaction_id": null,
54      "date": "2020-05-29",
55      "fees": 0,
56      "investment_transaction_id": "oq99Pz97joHQem4BNjXECev1E4B6L6sRzwANW",
57      "iso_currency_code": "USD",
58      "name": "INCOME DIV DIVIDEND RECEIVED",
59      "price": 0,
60      "quantity": 0,
61      "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ",
62      "subtype": "dividend",
63      "type": "cash",
64      "unofficial_currency_code": null
65    },
66    {
67      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
68      "amount": -1289.01,
69      "cancel_transaction_id": null,
70      "date": "2020-05-28",
71      "fees": 7.99,
72      "investment_transaction_id": "pK99jB9e7mtwjA435GpVuMvmWQKVbVFLWme57",
73      "iso_currency_code": "USD",
74      "name": "SELL Matthews Pacific Tiger Fund Insti Class",
75      "price": 27.53,
76      "quantity": -47.74104242992852,
77      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
78      "subtype": "sell",
79      "type": "sell",
80      "unofficial_currency_code": null
81    },
82    {
83      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
84      "amount": 7.7,
85      "cancel_transaction_id": null,
86      "date": "2020-05-27",
87      "fees": 7.99,
88      "investment_transaction_id": "LKoo1ko93wtreBwM7yQnuQ3P5DNKbKSPRzBNv",
89      "iso_currency_code": "USD",
90      "name": "BUY DoubleLine Total Return Bond Fund",
91      "price": 10.42,
92      "quantity": 0.7388014749727547,
93      "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
94      "subtype": "buy",
95      "type": "buy",
96      "unofficial_currency_code": null
97    }
98  ],
99  "item": {
100    "available_products": ["assets", "balance", "identity", "transactions"],
101    "billed_products": ["auth", "investments"],
102    "consent_expiration_time": null,
103    "error": null,
104    "institution_id": "ins_12",
105    "item_id": "8Mqq5rqQ7Pcxq9MGDv3JULZ6yzZDLMCwoxGDq",
106    "webhook": "https://www.genericwebhookurl.com/webhook"
107  },
108  "request_id": "iv4q3ZlytOOthkv",
109  "securities": [
110    {
111      "close_price": 27,
112      "close_price_as_of": null,
113      "cusip": "577130834",
114      "institution_id": null,
115      "institution_security_id": null,
116      "is_cash_equivalent": false,
117      "isin": "US5771308344",
118      "iso_currency_code": "USD",
119      "name": "Matthews Pacific Tiger Fund Insti Class",
120      "proxy_security_id": null,
121      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
122      "sedol": null,
123      "ticker_symbol": "MIPTX",
124      "type": "mutual fund",
125      "unofficial_currency_code": null
126    },
127    {
128      "close_price": 10.42,
129      "close_price_as_of": null,
130      "cusip": "258620103",
131      "institution_id": null,
132      "institution_security_id": null,
133      "is_cash_equivalent": false,
134      "isin": "US2586201038",
135      "iso_currency_code": "USD",
136      "name": "DoubleLine Total Return Bond Fund",
137      "proxy_security_id": null,
138      "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
139      "sedol": null,
140      "ticker_symbol": "DBLTX",
141      "type": "mutual fund",
142      "unofficial_currency_code": null
143    }
144  ],
145  "total_investment_transactions": 2
146}

Next steps

If you're ready to launch to Production, see the Launch checklist.

auth partnerships svb

Add Silicon Valley Bank to your app

Use Silicon Valley Bank with Plaid Auth to send and receive payments!

Partnership Silicon Valley Bank logo

Overview

The Silicon Valley Bank (SVB) and Plaid integration helps reduce risk, administrative work and costs of processing payments. This solution connects Plaid's instant account verification and SVB's ACH API functionality via a tokenized integration to help minimize the handling of clients’ bank and payments data.

Together, the Plaid and SVB integration helps give clients an efficient way to process payments directly from a bank. SVB supports instant account verification for both ACH Debits and ACH Credits.

If you have an SVB ACH API-enabled account with Plaid, view the guide to begin setting up the integration. If you do not have an account with the SVB ACH API but need additional information, visit the following SVB website for more information and SVB ACH API’s technical documentation.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Silicon Valley Bank account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Silicon Valley Bank processor_token, which allows you to quickly and securely verify a bank funding source via Silicon Valley Bank's API without having to store any sensitive banking information. Utilizing Plaid + Silicon Valley Bank enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Silicon Valley Bank in order to use the Plaid + Silicon Valley Bank integration. You'll also need to enable your Plaid account for the Silicon Valley Bank integration.

First, you will need to work with the Silicon Valley Bank team to sign up for a Silicon Valley Bank account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Silicon Valley Bank to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Silicon Valley Bank processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Silicon Valley Bank, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Silicon Valley Bank processor_token. You'll send this token to Silicon Valley Bank and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Silicon Valley Bank processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'svb_api',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Silicon Valley Bank Production credentials prior to initiating live payment transactions in the Silicon Valley Bank API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

virtual accounts payment confirmation

Payment Confirmation

Confirm when funds have settled in a virtual account

Plaid offers Payment Confirmation on top of our Payment Initiation APIs. Payment Confirmation provides confirmation of payments settling in your virtual account. Plaid will notify you when funds have settled so you can confidently release those funds to your end users. Each virtual account can receive or send funds on payment rails supported by the currency of the account.

The Payment Confirmation flow builds on the Payment Initiation flow, with two main differences:

  • Payments are initiated with the client-owned virtual account as the recipient.

  • Optionally, the current balance of the virtual account can be automatically swept (transferred) periodically to your bank account. To use this functionality, reach out to your Account Manager.

To your end user, there is no difference between initiating a payment to a virtual account and initiating a payment directly to the recipient bank account.

Confirming funds have settled

Make sure your virtual account is set up before following these steps. For more information on setting up an account, see Managing virtual accounts.

  1. Go through the Payment Initiation flow and initiate a payment.

    • Use the recipient_id associated with your wallet_id so Plaid knows to route the payment to your virtual account.

  2. The payment will settle in your virtual account. You will receive the following webhooks:

    • If you included a webhook URL when creating your link_token you will receive a status update that the payment is now SETTLED. This is the primary webhook that indicates payment confirmation.

    • If you configured a webhook through the developer dashboard, you will also receive a status update that a transaction of type PIS_PAY_IN transitioned from INITIATED to SETTLED in your virtual account. This webhook indicates an update to your virtual account with the funds that have settled (i.e., the transaction that corresponds to the payment that settled).

    • Alternatively, if you are not using webhooks, you can check if the payment has settled by calling /payment_initiation/payment/get with the payment_id from Step 1.

  3. Once the payment has settled, you can safely release funds to your end user.

In the UK, payments settle nearly instantly and run on the Faster Payment Services rails. In Europe, Plaid defaults to instant settlement times with SEPA Instant Credit rails when possible, and SEPA Credit Transfer otherwise.

Testing Payment Confirmation

You can begin testing Payment Confirmation in Sandbox by following the steps listed in the Add Virtual Accounts to your App guide. For Production access you will first need to submit a product access request Support ticket.

link

Link overview

Use Link to connect to your users' financial accounts with the Plaid API

image of Plaid Link UI

Introduction to Link

Plaid Link is the client-side component that your users will interact with in order to link their accounts to Plaid and allow you to access their accounts via the Plaid API.

Plaid Link will handle credential validation, multi-factor authentication, and error handling for each institution that Plaid supports. Link is supported via SDKs for all modern browsers and Platforms, including web, iOS, Android, as well as via React Native and mobile webviews, along with a community-supported wrapper for Flutter. To try Link, see Plaid Link Demo.

Link is the only available method for connecting accounts in Development and Production and is mandatory for all Plaid integrations. In the Sandbox test environment, Link can optionally be bypassed for testing purposes via /sandbox/public_token/create.

Want to build a Plaid-powered application using Link directly in your browser? The Plaid Basics interactive tutorial can walk you through the process.

Link flow overview

The diagram below shows a model of how Link is used to obtain a public_token, which can then be exchanged for an access_token, which is used to authenticate requests to the Plaid API.

The Plaid flow begins when your user wants to connect their bank account to your app.
Step diagram
1Call /link/token/create to create a link_token and pass the temporary token to your app's client.
Step 1 diagram
2Use the link_token to open Link for your user. In the onSuccess callback, Link will provide a temporary public_token.
Step 2 diagram
3Call /item/public_token/exchange to exchange the public_token for a permanent access_token and item_id for the new Item.
Step 3 diagram
4Store the access_token and use it to make product requests for your user's Item.
Step 4 diagram

In code, this flow is initiated by creating a link_token and using it to initialize Link. The link_token can be configured with the Plaid products you will be using and the countries you will need to support. Once the user has logged in via Link, Link will issue a callback containing a public_token, which can be exchanged for an access_token via /item/public_token/exchange.

Initializing Link

Link is initialized by passing the link_token to Link. The exact implementation details for passing the link_token will vary by platform. For detailed instructions, see the page for your specific platform: web, iOS, Android, React Native or mobile webview.

For recommendations on configuring the link_token for your use case, see Choosing when to initialize products.

Supporting OAuth

Some institutions use an OAuth authentication flow, in which Plaid Link redirects the end user to their bank's website or mobile app to authenticate. To learn how to connect to an institution that uses OAuth, see the OAuth guide.

Customizing Link

You can customize parts of Link's flow, including some text elements, the institution select view, and the background color, and enable additional features like the Account Select view straight from the Dashboard. You can preview your changes in realtime and then publish them instantly once you're ready to go live. For more details, see Link customization.

To help you take advantage of the options available for customizing and configuring Link, Plaid offers a best practices guide with recommendations for how to initialize and configure Link within your app.

Link's appearance will also automatically change if the institution selected is not in a healthy state. For more details, see Institution status in Link.

Returning user flows

The returning user flow allows you to enable a faster Plaid Link experience for your users who already use Plaid. To learn more, see Returning user experience.

Error-handling flows

If your application will access an Item on a recurring basis, rather than just once, it should support update mode. Update mode allows you to refresh an Item if it enters an error state, such as when a user changes their password or MFA information. For more information, see Updating an Item.

It's also recommended to have special handling for when a user attempts to link the same Item twice. Requesting access tokens for duplicate Items can lead to higher bills and end-user confusion. To learn more, see preventing duplicate Items.

Occasionally, Link itself can enter an error state if the user takes over 30 minutes to complete the Link process. For information on handling this flow, see Handling invalid Link tokens.

Optimizing Link conversion

How you configure Link can have a huge impact on the percentage of users who successfully complete the Link flow. To ensure you're maximizing conversion, see Best practices for Link conversion.

Link token migration

Prior to July 2020, Link was initialized using a public key instead of a link_token. If you are an existing Plaid developer using a Plaid public key, it is recommended that you migrate to a link_token-based implementation as soon as possible, using the instructions in the Link token migration guide. For those who are not yet ready to migrate, instructions on maintaining a legacy integration can be found in the legacy integration guide.

Troubleshooting

Since all your users will go through Link, it's important to build as robust an integration as possible. For details on dealing with common problems, see the Troubleshooting section.

Link updates

Plaid periodically updates Link to add new functionality and improve conversion. These changes will be automatically deployed. Any test suites and business logic in your app should be robust to the possibility of changes to the user-facing Link flow.

auth coverage automated

Automated Micro-deposits

Learn how to authenticate your users in a secure and frictionless micro-deposit flow

The Automated Micro-deposit flow

The Automated Micro-deposits authentication flow is supported for over 1,000 financial institutions in the US only, accounting for approximately <1% of depository accounts. Plaid will make a single micro-deposit and then automatically verify it within one to two business days.

Instant Match Link flow

You can try out the Automated Micro-deposits flow in Link Demo. See more details in our testing guide.

A user connects their financial institution using the following connection flow:

  1. Starting on a page in your app, the user clicks an action that opens Plaid Link, with the correct Auth configuration.
  2. Inside of Plaid Link, the user selects their institution, authenticates with their credentials, provides their account and routing number, and enters in their legal name.
  3. Upon successful authentication, Link closes with a public_token and a metadata account status of pending_automatic_verification.
  4. Behind the scenes, Plaid sends a single micro-deposit to the user's account and will automatically verify the deposited amounts within one to two business days.
  5. When verification succeeds or fails, Plaid sends an Auth webhook, which you can use to notify the user that their account is ready to move money. Once this step is done, your user's Auth data is verified and ready to fetch.

Configure & Create a link_token

Create a link_token with the following parameters:

  • products array containing auth -- unlike with Same-Day Micro-deposits, you can also include other products besides auth when creating a Link token for use with Automated Micro-deposits, but auth must be present.
  • country_codes set to ['US'] – Micro-deposit verification is currently only available in the United States.
  • A webhook URL to receive a POST HTTPS request sent from Plaid's servers to your application server, after Automated Micro-deposits succeeds or fails verification of a user's micro-deposits.
  • auth object should specify "automated_microdeposits_enabled": true
Select Language
1const request: LinkTokenCreateRequest = {
2  user: { client_user_id: new Date().getTime().toString() },
3  client_name: 'Plaid App',
4  products: [Products.Auth],
5  country_codes: [CountryCode.Us],
6  language: 'en',
7  auth: {
8    automated_microdeposits_enabled: true,
9  },
10};
11try {
12  const response = await plaidClient.linkTokenCreate(request);
13  const linkToken = response.data.link_token;
14} catch (error) {
15    // handle error
16}

Initialize Link with a link_token

After creating a link_token for the auth product, use it to initialize Plaid Link.

When the user inputs their username and password, and account and routing numbers for the financial institution, the onSuccess() callback function will return a public_token, with verification_status equal to 'pending_automatic_verification'.

1const linkHandler = Plaid.create({
2  // Fetch a link_token configured for 'auth' from your app server
3  token: (await $.post('/create_link_token')).link_token,
4  onSuccess: (public_token, metadata) => {
5    // Send the public_token and accounts to your app server
6    $.post('/exchange_public_token', {
7      publicToken: public_token,
8      accounts: metadata.accounts,
9    });
10
11    metadata = {
12      ...,
13      link_session_id: String,
14      institution: { name: 'Bank of the West', institution_id: 'ins_100017' },
15      accounts: [{
16        id: 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D',
17        mask: '1234',
18        name: null,
19        type: 'depository',
20        subtype: 'checking' | 'savings',
21        verification_status: 'pending_automatic_verification'
22      }]
23    }
24  },
25  // ...
26});
27
28// Open Link on user-action
29linkHandler.open();
Display a "pending" status in your app

Because Automated verification usually takes between one to two days to complete, we recommend displaying a UI in your app that communicates to a user that verification will occur automatically and is currently pending.

You can use the verification_status key returned in the onSuccess metadata.accounts object once Plaid Link closes successfully.

1verification_status: 'pending_automatic_verification';

You can also fetch the verification_status for an Item's account via the Plaid API to obtain the latest account status.

Exchange the public token

In your own backend server, call the /item/public_token/exchange endpoint with the Link public_token received in the onSuccess callback to obtain an access_token. Persist the returned access_token and item_id in your database in relation to the user.

Note that micro-deposits will only be delivered to the ACH network in the Production environment. To test your integration outside of Production, see Testing automated micro-deposits in Sandbox.

Select group for content switcher
Select Language
1// publicToken and accountID are sent from your app to your backend-server
2const accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D';
3const publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d';
4
5// Obtain an access_token from the Link public_token
6const response = await client
7  .itemPublicTokenExchange({
8    public_token: publicToken,
9  })
10  .catch((err) => {
11    // handle error
12  });
13const accessToken = response.access_token;
1{
2  "access_token": "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755",
3  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
4  "request_id": "m8MDnv9okwxFNBV"
5}

Handle Auth webhooks

Before you can call /auth/get to fetch Auth data for a user's access_token, a micro-deposit first need to post successfully to the user's bank account. Because Plaid uses Same Day ACH to send a single micro-deposit amount, this process usually takes between one to two days.

Once the deposit has arrived in the user's account, Plaid will automatically verify the deposit transaction and send an AUTOMATICALLY_VERIFIED webhook to confirm the account and routing numbers have been successfully verified.

Attempting to call /auth/get on an unverified access_token will result in a PRODUCT_NOT_READY error.

1> POST https://your_app_url.com/webhook
2
3{
4  "webhook_type": "AUTH",
5  "webhook_code": "AUTOMATICALLY_VERIFIED",
6  "item_id": "zeWoWyv84xfkGg1w4ox5iQy5k6j75xu8QXMEm",
7  "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D"
8}

Occasionally automatic verification may fail, likely due to erroneous user input, such as an incorrect account and routing number pair. If the Item is unable to be verified within seven days, Plaid will send a VERIFICATION_EXPIRED webhook. When verification fails, the Item is permanently locked; we recommend prompting your user to retry connecting their institution via Link.

1> POST https://your_app_url.com/webhook
2
3{
4  "webhook_type": "AUTH",
5  "webhook_code": "VERIFICATION_EXPIRED",
6  "item_id": "zeWoWyv84xfkGg1w4ox5iQy5k6j75xu8QXMEm",
7  "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D"
8}

If Plaid encounters an ITEM_LOGIN_REQUIRED error during attempted validation, this may mean that Plaid lost access to the user's account after sending this micro-deposit but before being able to verify it. If this occurs, send the user through the update mode flow to re-verify their account.

The example code below shows how to handle AUTOMATICALLY_VERIFIED and VERIFICATION_EXPIRED webhooks and call /auth/get to retrieve account and routing data.

If you are using the Sandbox environment, you can use the /sandbox/item/set_verification_status endpoint to test your integration.

Select group for content switcher
Select Language
1// This example uses Express to receive webhooks
2const app = require('express')();
3const bodyParser = require('body-parser');
4app.use(bodyParser);
5
6app.post('/webhook', async (request, response) => {
7  const event = request.body;
8
9  // Handle the event
10  switch (event.webhook_code) {
11    case 'AUTOMATICALLY_VERIFIED':
12      const accessToken = lookupAccessToken(event.item_id);
13      const request: AuthGetRequest = { access_token: accessToken };
14      const authResponse = await client.authGet(request);
15      const numbers = authResponse.numbers;
16      break;
17    case 'VERIFICATION_EXPIRED':
18      // handle verification failure; prompt user to re-authenticate
19      console.error('Verification failed for', event.item_id);
20      break;
21    default:
22      // Unexpected event type
23      return response.status(400).end();
24  }
25
26  // Return a response to acknowledge receipt of the event
27  response.json({ received: true });
28});
29
30app.listen(8000, () => console.log('Running on port 8000'));

Check the account verification status (optional)

In some cases you may want to implement logic to display the verification_status of an Item that is pending automated verification in your app. The /accounts/get API endpoint allows you to query this information.

Select group for content switcher
Select Language
1// Fetch the accountID and accessToken from your database
2const accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D';
3const accessToken = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755';
4const request: AccountsGetRequest = {
5  access_token: accessToken,
6};
7const response = await client.accountsGet(request).catch((err) => {
8  // handle error
9});
10const account = response.accounts.find((a) => a.account_id === accountID);
11const verificationStatus = account.verification_status;
1{
2  "accounts": [
3    {
4      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
5      "balances": { Object },
6      "mask": "0000",
7      "name": "Plaid Checking",
8      "official_name": "Plaid Gold Checking",
9      "type": "depository"
10      "subtype": "checking" | "savings",
11      "verification_status":
12        "pending_automatic_verification" |
13        "automatically_verified" |
14        "verification_expired",
15    },
16    ...
17  ],
18  "item": { Object },
19  "request_id": String
20}

Fetch Auth data

Finally, we can retrieve Auth data once automated verification has succeeded:

Select group for content switcher
Select Language
1const accessToken = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755';
2
3// Instantly fetch Auth numbers
4const request: AuthGetRequest = {
5  access_token: accessToken,
6};
7const response = await client.authGet(request).catch((err) => {
8  // handle error
9});
10const numbers = response.numbers;
1{
2  "numbers": {
3    "ach": [
4      {
5        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
6        "account": "9900009606",
7        "routing": "011401533",
8        "wire_routing": "021000021"
9      }
10    ],
11    "eft": [],
12    "international": [],
13    "bacs": []
14  },
15  "accounts": [
16    {
17      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
18      "balances": { Object },
19      "mask": "0000",
20      "name": null,
21      "official_name": null,
22      "verification_status": "automatically_verified",
23      "subtype": "checking" | "savings",
24      "type": "depository"
25    }
26  ],
27  "item": { Object },
28  "request_id": "m8MDnv9okwxFNBV"
29}

Check out the /auth/get API reference documentation to see the full Auth request and response schema.

Handling Link events

For a user who goes through the Automated Micro-deposit flow, the TRANSITION_VIEW (view_name = NUMBERS) event will occur after SUBMIT_CREDENTIALS, and in the onSuccess callback the verification_status will be pending_automatic_verification.

1OPEN (view_name = CONSENT)
2TRANSITION_VIEW view_name = SELECT_INSTITUTION)
3SEARCH_INSTITUTION
4SELECT_INSTITUTION
5TRANSITION_VIEW (view_name = CREDENTIAL)
6SUBMIT_CREDENTIALS
7TRANSITION_VIEW (view_name = LOADING)
8TRANSITION_VIEW (view_name = MFA, mfa_type = code)
9SUBMIT_MFA (mfa_type = code)
10TRANSITION_VIEW (view_name = LOADING)
11TRANSITION_VIEW (view_name = SELECT_ACCOUNT)
12TRANSITION_VIEW (view_name = NUMBERS)
13TRANSITION_VIEW (view_name = LOADING)
14TRANSITION_VIEW (view_name = CONNECTED)
15HANDOFF
16onSuccess (verification_status: pending_automatic_verification)

account activity

Dashboard logs and troubleshooting

Discover logging and troubleshooting information available in the Plaid dashboard

Logs for webhooks, Link, and API requests

The Plaid dashboard Activity Log shows the past 14 days of API activity. Using the dashboard, you can see a record of all requests and responses, as well as all webhooks sent by the Plaid API, and all Link events. Note that viewing Link events in the dashboard requires the use of Link tokens; implementations using the legacy public key will not display Link events in the dashboard.

image of Plaid API activity, showing requests, response codes, and webhooks

You can view the details of any request, response, webhook, or event, and view error information for any failed API request.

A detailed image of failed API request information in the dashboard

Logs for Payment Initiation and Transfer

The Payment Initiation (UK and Europe) and Transfer products also have their own logs in the Plaid dashboard. If you are enabled for these products, links to view activity will appear in the Activity menu within the dashboard. Using these logs, you can view the status and history of payment and transfer attempts. This information is also available via the API; for more details, see the API documentation for Payment Initiation and Transfer.

Troubleshooting institution status

The Plaid dashboard contains an Institution Status pane, which allows you to view details and stats about institution connectivity over the past two weeks, as well as any recent downtime or special notes about the institution. You can also use this view to search institutions to see whether they are supported by Plaid and which Plaid products can be used with them. Most of this information is also available via the API; for more information on programmatically retrieving institution status, see Institutions API endpoints.

Institution status details

The graph at the top of the page shows institution status over the past two weeks, while the boxes below the graph show the current institution status. The time range used for calculating the current institution status may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more.

Plaid displays both Item add success rates (success adding new Items) and Item update success rates (success refreshing data for existing Items). The success rate as shown on the main status page is the Item add success rate.

All success rates reflect the percentage of successful attempts to retrieve data. Both Plaid errors and institution errors are combined when calculating the percentage of unsuccessful attempts. User errors, such as an Item add failing due to an incorrect password entered during Link, are not considered when calculating success rates.

All success rates are rounded down to the nearest percentage point. A success rate of 99% or higher indicates that the institution is considered healthy.

Insufficient data and delayed data

If the institution has not had enough Plaid traffic during the window being evaluated to produce meaningful health data, the "Insufficient Data" message will be displayed. This is most likely to affect small institutions. If this occurs, try using the Item Debugger instead to diagnose the problem.

If Plaid has not been able to update data from the institution for over two days, the institution status may appear as "delayed". If it has been at least two weeks since the last successful institution update, or if Plaid is aware of a problem in updating data that is likely to take over two weeks to resolve, the institution status will appear as "stopped".

Data freshness

If you have at least 25 Transactions-enabled Items associated with a given institution, the Institution Status page will also show a Data Freshness display, including a total Item count and a percentage breakdown of when the Items were last updated within certain time intervals. Note that this information is specific to Transactions and is calculated based on your own users' Items, not global Plaid Item statistics.

Troubleshooting with Item Debugger

To view the status of a specific Item or Link session in the dashboard, you can use the Item Debugger. You can look up Items and Link sessions by client_user_id, item_id, access_token, link_token, or link_session_id. Troubleshooting information available includes error codes and suggested troubleshooting steps you can take to resolve any errors.

errors payment

Payment Errors

Errors specific to the Payment Initiation product

PAYMENT_BLOCKED

The payment was blocked for violating compliance rules.
Common causes
Troubleshooting steps
1http code 400
2{
3 "error_type": "PAYMENT_ERROR",
4 "error_code": "PAYMENT_BLOCKED",
5 "error_message": "payment blocked",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

PAYMENT_CANCELLED

The payment was cancelled.
Sample user-facing error message
Payment cancelled: Try making your payment again or select a different bank to continue.
Common causes
  • The payment was cancelled by the user during the authorisation process
Troubleshooting steps
1http code 400
2{
3 "error_type": "PAYMENT_ERROR",
4 "error_code": "PAYMENT_CANCELLED",
5 "error_message": "user cancelled the payment",
6 "display_message": "Try making your payment again or select a different bank to continue.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

PAYMENT_INSUFFICIENT_FUNDS

The account has insufficient funds to complete the payment.
Sample user-facing error message
Insufficient funds: There isn't enough money in this account to complete the payment. Try again, or select another account or bank.
Common causes
  • The account selected has insufficient funds to complete the payment.
Troubleshooting steps
1http code 400
2{
3 "error_type": "PAYMENT_ERROR",
4 "error_code": "PAYMENT_INSUFFICIENT_FUNDS",
5 "error_message": "insufficient funds to complete the request",
6 "display_message": "There isn't enough money in this account to complete the payment. Try again, or select another account or bank.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

PAYMENT_INVALID_RECIPIENT

The recipient was rejected by the chosen institution.
Sample user-facing error message
Payment failed: Try making your payment again or select a different bank to continue.
Common causes
  • The recipient name is too long or contains special characters.
  • The address is too long or contains special characters.
  • The account number is invalid.
Troubleshooting steps
1http code 400
2{
3 "error_type": "PAYMENT_ERROR",
4 "error_code": "PAYMENT_INVALID_RECIPIENT",
5 "error_message": "payment recipient invalid",
6 "display_message": "The payment recipient is invalid for the selected institution. Create a new payment with a different recipient.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

PAYMENT_INVALID_REFERENCE

The reference was rejected by the chosen institution.
Sample user-facing error message
Payment failed: Try making your payment again or select a different bank to continue.
Common causes
  • The reference is too long or contains special characters.
Troubleshooting steps
1http code 400
2{
3 "error_type": "PAYMENT_ERROR",
4 "error_code": "PAYMENT_INVALID_REFERENCE",
5 "error_message": "payment reference invalid",
6 "display_message": "The payment reference is invalid for the selected institution. Create a new payment with a different reference.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

PAYMENT_INVALID_SCHEDULE

The schedule was rejected by the chosen institution.
Sample user-facing error message
Payment failed: Try making your payment again or select a different bank to continue.
Common causes
  • The chosen institution does not support negative payment execution days.
  • The first payment date is a holiday or on a weekend.
Troubleshooting steps
1http code 400
2{
3 "error_type": "PAYMENT_ERROR",
4 "error_code": "PAYMENT_INVALID_SCHEDULE",
5 "error_message": "payment schedule invalid",
6 "display_message": "The payment schedule is invalid for the selected institution. Create a new payment with a different schedule.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

PAYMENT_REJECTED

The payment was rejected by the chosen institution.
Sample user-facing error message
Payment failed: Try making your payment again or select a different bank to continue.
Common causes
  • The amount was too large.
  • The payment was considered suspicious by the institution.
Troubleshooting steps
1http code 400
2{
3 "error_type": "PAYMENT_ERROR",
4 "error_code": "PAYMENT_REJECTED",
5 "error_message": "payment rejected",
6 "display_message": "The payment was rejected by the institution. Try again, or select another account or bank.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

PAYMENT_SCHEME_NOT_SUPPORTED

The requested payment scheme is not supported by the chosen institution.
Sample user-facing error message
Payment failed: Try making your payment again or select a different bank to continue.
Common causes
Troubleshooting steps
1http code 400
2{
3 "error_type": "PAYMENT_ERROR",
4 "error_code": "PAYMENT_SCHEME_NOT_SUPPORTED",
5 "error_message": "payment scheme not supported",
6 "display_message": "The payment scheme is not supported by the institution. Either change scheme or select another institution.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

auth coverage same day

Same Day Micro-deposits

Learn how to authenticate your users with a manually verified micro-deposit

Overview

Same Day Micro-deposits can be used to authenticate any bank account in the US, but especially for the ~2,000 institutions that don't support Instant Auth, Instant Match, or Automated Micro-deposit verification. Plaid will make a deposit that will post within one business day (using Same Day ACH, which is roughly two days faster than the standard micro-deposit experience of two to three days). Users are instructed to manually verify the code in the transaction description deposited in the account.

Same Day Micro-deposits Link flow

The Same Day Micro-deposit flow

A user connects their financial institution using the following connection flow:

  1. Starting on a page in your app, the user clicks an action that opens Plaid Link with the correct Auth configuration.
  2. Inside of Plaid Link, the user enters the micro-deposit initiation flow and provides their legal name, account and routing number.
  3. Upon successful authentication, Link closes with a public_token and a metadata account status of pending_manual_verification.
  4. Behind the scenes, Plaid sends a micro-deposit to the user's account that will post within one to two business days.
  5. After one to two days, the user is prompted to verify the code in the transaction description in their account, by opening Link with a generated link_token.

Plaid will not reverse the $0.01 micro-deposit credit.

When these steps are done, your user's Auth data is verified and ready to fetch.

Demoing the flow in Link

You can try out the Same Day Micro-deposit flow in Link Demo. For instructions on triggering the flow, see the testing guide.

Implementation steps

Create a link_token

To integrate with the Same Day Micro-deposit flow, your application must be using Link Tokens rather than public keys. If you have not already migrated to Link Tokens, please do so following this guide.

Create a link_token with the following parameters:

  • products array should include only auth as a product when using same-day manual micro-deposit verification. While in most cases additional products can be added to existing Plaid Items, Items created for same-day manual micro-deposit verification are an exception and cannot be used with any Plaid products other than Auth.
  • country_codes set to ['US'] – Micro-deposit verification is currently only available in the United States.
  • auth object should specify "same_day_microdeposits_enabled": true
Select Language
1const request: LinkTokenCreateRequest = {
2  user: { client_user_id: new Date().getTime().toString() },
3  client_name: 'Plaid App',
4  products: [Products.Auth],
5  country_codes: [CountryCode.Us],
6  language: 'en',
7  auth: {
8    same_day_microdeposits_enabled: true,
9  },
10};
11try {
12  const response = await plaidClient.linkTokenCreate(request);
13  const linkToken = response.data.link_token;
14} catch (error) {
15    // handle error
16}
Initialize Link with a link_token

After creating a link_token for the auth product, use it to initialize Plaid Link.

When the user successfully inputs their account and routing numbers, the onSuccess() callback function will return a public_token, with verification_status equal to 'pending_manual_verification'.

1const linkHandler = Plaid.create({
2  // Fetch a link_token configured for 'auth' from your app server
3  token: (await $.post('/create_link_token')).link_token,
4  onSuccess: (public_token, metadata) => {
5    // Send the public_token and connected accounts to your app server
6    $.post('/exchange_public_token', {
7      publicToken: public_token,
8      accounts: metadata.accounts,
9    });
10
11    metadata = {
12      ...,
13      link_session_id: String,
14      institution: {
15        name: null,          // name is always null for Same Day Micro-deposits
16        institution_id: null // institution_id is always null for Same Day Micro-deposits
17      },
18      accounts: [{
19        id: 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D',
20        mask: '1234',
21        name: null,
22        type: 'depository',
23        subtype: 'checking' | 'savings',
24        verification_status: 'pending_manual_verification'
25      }]
26    }
27  },
28  // ...
29});
30
31// Open Link on user-action
32linkHandler.open();
Display a "pending" status in your app

Because Same Day verification usually takes one business day to complete, we recommend displaying a UI in your app that communicates to a user that verification is currently pending.

You can use the verification_status key returned in the onSuccess metadata.accounts object once Plaid Link closes successfully.

1verification_status: 'pending_manual_verification';

You can also fetch the verification_status for an Item's account via the Plaid API, to obtain the latest account status.

Exchange the public token

In your own backend server, call the /item/public_token/exchange endpoint with the Link public_token received in the onSuccess callback to obtain an access_token. Persist the returned access_token and item_id in your database in relation to the user.

When using same-day micro-deposit verification, only one account can be associated with each access token. If you want to allow a user to link multiple accounts at the same institution using same-day micro-deposits, you will need to create a new Link flow and generate a separate access token for each account.

Note that micro-deposits will only be delivered to the ACH network in the Production environment, and not in Development. To test your integration outside of Production, see Testing Same Day Micro-deposits in Sandbox.

Select group for content switcher
Select Language
1// publicToken and accountID are sent from your app to your backend-server
2const accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D';
3const publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d';
4
5// Obtain an access_token from the Link public_token
6const response = await client
7  .itemPublicTokenExchange({
8    public_token: publicToken,
9  })
10  .catch((err) => {
11    // handle error
12  });
13const accessToken = response.access_token;
1{
2  "access_token": "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755",
3  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
4  "request_id": "m8MDnv9okwxFNBV"
5}
Check the account verification status (optional)

In some cases you may want to implement logic in your app to display the verification_status of an Item that is pending manual verification. The /accounts/get API endpoint allows you to query this information.

To be notified via webhook when Plaid has sent the micro-deposit to your end user, see micro-deposit events.

Select group for content switcher
Select Language
1// Fetch the accountID and accessToken from your database
2const accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D';
3const accessToken = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755';
4const request: AccountsGetRequest = {
5  access_token: accessToken,
6};
7const response = await client.accountsGet(request).catch((err) => {
8  // handle error
9});
10const account = response.accounts.find((a) => a.account_id === accountID);
11const verificationStatus = account.verification_status;
1{
2  "accounts": [
3    {
4      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
5      "balances": { Object },
6      "mask": "0000",
7      "name": null,
8      "official_name": null,
9      "type": "depository"
10      "subtype": "checking" | "savings",
11      "verification_status":
12        "pending_manual_verification" |
13        "manually_verified" |
14        "verification_failed",
15    },
16    ...
17  ],
18  "item": { Object },
19  "request_id": String
20}
Prompt user to verify micro-deposit code in Link

After one to two business days, the micro-deposit sent to the user's account is expected to be posted. To securely verify a Same Day Micro-deposits account, your user needs to come back into Link to verify the code in the transaction description.

When the micro-deposit posts to your end user's bank account, the transaction description will be written with the format:

1#XXX <clientName> ACCTVERIFY

The # will be followed with the three letter code required for verification. The <clientName> is defined by the value of the client_name parameter that was used to create the link_token that initialized Link.

Users with business or corporate accounts that have ACH debit blocks enabled on their account may need to authorize Plaid's Company / Tax ID, 1460820571, to avoid any issues with linking their accounts.

To optimize conversion, we strongly recommend sending your user a notification (e.g. email, SMS, push notification) prompting them to come back into your app and verify the micro-deposit code. To be notified via webhook when Plaid has sent the micro-deposit to your end user, see micro-deposit events.

Verification of Same Day Micro-deposits is performed in two steps:

  1. In your backend server, create a new link_token from the associated access_token for the given user.
  2. Pass the generated link_token into your client-side app, using the token parameter in the Link configuration. This will automatically trigger the micro-deposit verification flow in Link.
Create a new link_token from a persistent access_token

Generate a link_token for verifying micro-deposits by passing the user's associated access_token to the /link/token/create API endpoint. Note that the products field should not be set because the micro-deposits verification flow does not change the products associated with the given access_token.

Select group for content switcher
Select Language
1// Using Express
2app.post('/api/create_link_token', async function (request, response) {
3  // Get the client_user_id by searching for the current user
4  const user = await User.find(...);
5  const clientUserId = user.id;
6  const request = {
7    user: {
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    language: 'en',
12    webhook: 'https://webhook.sample.com',
13    country_codes: [CountryCode.Us],
14    access_token: 'ENTER_YOUR_ACCESS_TOKEN',
15  };
16  try {
17    const createTokenResponse = await client.linkTokenCreate(request);
18    response.json(createTokenResponse.data);
19  } catch (error) {
20    // handle error
21  }
22});
Initialize Link with the generated link_token

In your client-side app, pass the generated link_token into the Link token parameter. Link will automatically detect that Same Day verification is required for the Item and will open directly into the verification flow (see the image above).

In Link, the user will be prompted to log in to their personal banking portal to confirm the code in the micro-deposit transaction description. Upon successful entry of the code, the onSuccess callback will be fired, with an updated verification_status: 'manually_verified'. The verification code will be case-insensitive.

There is no time limit for the user to verify the deposit. A user has three attempts to enter the code correctly, after which the Item will be permanently locked for security reasons. See INCORRECT_DEPOSIT_VERIFICATION and PRODUCT_NOT_READY for errors that may occur during the micro-deposit initiation and verification flow.

1const linkHandler = Plaid.create({
2  token: await fetchLinkTokenForMicrodepositsVerification(),
3  onSuccess: (public_token, metadata) => {
4    metadata = {
5      accounts: [{
6        ...,
7        verification_status: 'manually_verified',
8      }],
9    };
10  },
11  // ...
12});
13
14// Open Link to verify micro-deposit amounts
15linkHandler.open();

An Item's access_token does not change when verifying micro-deposits, so there is no need to repeat the exchange token process.

Fetch Auth data

Finally, we can retrieve Auth data once the user has manually verified their account through Same Day Micro-deposits:

Select group for content switcher
Select Language
1const accessToken = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755';
2
3// Instantly fetch Auth numbers
4const request: AuthGetRequest = {
5  access_token: accessToken,
6};
7const response = await client.authGet(request).catch((err) => {
8  // handle error
9});
10const numbers = response.numbers;
1{
2  "numbers": {
3    "ach": [
4      {
5        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
6        "account": "9900009606",
7        "routing": "011401533",
8        "wire_routing": "021000021"
9      }
10    ],
11    "eft": [],
12    "international": [],
13    "bacs": []
14  },
15  "accounts": [
16    {
17      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
18      "balances": { Object },
19      "mask": "0000",
20      "name": null,
21      "official_name": null,
22      "verification_status": "manually_verified",
23      "subtype": "checking" | "savings",
24      "type": "depository"
25    }
26  ],
27  "item": { Object },
28  "request_id": "m8MDnv9okwxFNBV"
29}

Check out the /auth/get API reference documentation to see the full Auth request and response schema.

Same Day Micro-deposit flow configuration options

In addition to the default flow, Same Day Micro-deposits have two optional flow settings you can enable: to expose more users to the Same Day micro-deposit flow, you can enable Auth type select, or to limit users' exposure to the flow, you can enable Reroute to credentials.

The setting that is best for you will depend on your use case, your risk exposure, and which other Plaid products you use. Learn more about how to optimize your configuration and manage risk under best practices.

Same Day Micro-deposit flow options are configured via the auth object in the /link/token/create request. This enables you to decide which sessions are enabled for which flows; for example, you can enable different flows based on users' risk profiles.

Default flow

For many customers, the Same Day Micro-deposits is best configured as an option when credential-based Auth Types fail. This maximizes the conversion of items that have broader coverage of additional data products (i.e. Balance, Identity, Transactions, etc), but also allows extended Auth coverage. The flow is only presented as an option when the user experiences a failure in Link. There is no active choice for the consumer up front in Link.

The following table describes the primary entry points into the manual micro-deposit flow when configured as an option at Link failure points:

ExitErrorInstitution SearchInstitution SearchInstitution Select
When user clicks X action buttonWhen user encounters any errorWhen no results are foundWhen user scrolls to end of resultsWhen institution health is poor

This is the default flow for accessing Same-day micro-deposits and no special configuration settings are required to trigger it.

To trigger this flow via the Link demo specify Auth in the Product dropdown menu and then Launch Demo. Trigger empty search results (type in a search query like ‘xyz’) or the Exit Pane (by closing Link) and select Link with account numbers.

Reroute to Credentials

Reroute to Credentials is a feature for Same Day Micro-deposits that validates the routing number provided by the user and provides a recommendation to connect via credential-based methods if the routing number corresponds to a supported institution. This enables a user to connect their account more quickly and increases the number of Plaid Items that are eligible for additional risk products such as Balance, Identity, and Signal.

Reroute to Credentials can be configured on a per-session basis via the auth object in the /link/token/create request, or you can reach out to your Plaid account manager to enable it by default for all Link sessions.

In some cases, when rerouting a user to a supported institution, Plaid may show a list of institutions instead of a single institution. This can occur when a financial institution has multiple different brands that share a common routing number.

Optional Reroute

Optional Reroute to Credentials is best for developers who would like to make a recommendation for the user to connect via credentials, but not block the user from proceeding with the Same Day Micro-deposits flow. This flow will provide a reminder to the user that the institution is supported, and detail the benefits of instant connection, while also leaving the manual verification option in place. To enable Optional reroute, set auth.reroute_to_credentials to OPTIONAL in the /link/token/create call.

Single Institution Optional RerouteMultiple Institution Optional Reroute
Forced Reroute

Forced Reroute to Credentials is best for developers who would like to restrict the user to connect via credentials if the institution is supported on a credential-based flow and stop the user from proceeding with the Same Day Micro-deposits flow. This flow is designed to block a user from connecting manually for institutions that are supported via credentials in high ACH risk use cases. To enable Forced Reroute, set auth.reroute_to_credentials to FORCED in the /link/token/create call.

Single Institution Forced RerouteMultiple Institution Forced Reroute
Sample code for reroute to credentials
Select Language
1const request: LinkTokenCreateRequest = {
2  user: { client_user_id: new Date().getTime().toString() },
3  client_name: 'Plaid App',
4  products: [Products.Auth],
5  country_codes: [CountryCode.Us],
6  language: 'en',
7  auth: {
8    same_day_microdeposits_enabled: true,
9    reroute_to_credentials: 'OPTIONAL',
10  },
11};
12try {
13  const response = await plaidClient.linkTokenCreate(request);
14  const linkToken = response.data.link_token;
15} catch (error) {
16    // handle error
17}

Auth Type Select

Auth Type Select is a Link configuration of Same Day Micro-deposits which shows a pane upfront, enabling consumers to actively choose between instant (i.e. Instant Auth, Instant Match, Automated Micro-deposits) and manual account authentication (i.e. Same Day Micro-deposits) at the start of the Plaid Link flow. By offering this choice, you can proactively offer the authentication method for consumers who either cannot or do not opt for credential-based Auth Types.

To demo Auth Type Select via the Plaid Link demo, specify United States and Auth in the Country and Product dropdown menu respectively. Toggle on Auth Type Select, then Launch Demo.

To enable Auth Type Select, when calling /link/token/create, the auth_type_select_enabled boolean in the auth object should be set to true.

When to use Auth Type Select

Auth Type Select is best suited for developers who expect that a substantial portion of their consumers would prefer to authenticate manually, and who prefer to maximize Auth coverage over other data products. Examples of this may include Business Account Verification use cases where a high percentage of users are not expected to have access to credentials of a bank account, yet do have access to the transaction records, and therefore can verify micro-deposits.

Customers that see the greatest success with the Auth Type Select configuration have a substantial portion of users (over half, as a rule of thumb) who cannot or will not connect by logging into their bank, who have invested in fraud risk mitigations or have a low risk use case, and/or have very high intent users (such as users connecting a bank account to receive a payment).

Some developers observe an increase in conversion of verified Auth data with this configuration. However, this configuration reduces coverage of other products (like Balance or Identity) as those products are only available via credential-based Auth Types. When offered the manual option upfront, more users may choose to Link manually. Users who opt to connect via micro-deposits can have lower conversion than Instant Auth because the flow requires more steps for a user, including returning to Link the next day to verify micro-deposits. It may encourage users to connect via micro-deposits who would otherwise connect via credential-based Auth Types (if the micro-deposits option was not available upfront).

This configuration is best for customers who want to maximize Auth coverage and can tolerate reduced coverage of other products like Balance and Identity.

Sample code for Auth Type Select
Select Language
1const request: LinkTokenCreateRequest = {
2  user: { client_user_id: new Date().getTime().toString() },
3  client_name: 'Plaid App',
4  products: [Products.Auth],
5  country_codes: [CountryCode.Us],
6  language: 'en',
7  auth: {
8    same_day_microdeposits_enabled: true,
9    auth_type_select_enabled: true,
10  },
11};
12try {
13  const response = await plaidClient.linkTokenCreate(request);
14  const linkToken = response.data.link_token;
15} catch (error) {
16    // handle error
17}

Handling Link events

When a user goes through the Same Day micro-deposits flow, the session will have the TRANSITION_VIEW (view_name = NUMBERS) event, and in the onSuccess callback the verification_status will be pending_manual_verification because the user will have to return to Link to verify their micro-deposit at a later Link session.

1OPEN (view_name = CONSENT)
2TRANSITION_VIEW (view_name = SELECT_INSTITUTION)
3SEARCH_INSTITUTION
4TRANSITION_VIEW (view_name = NUMBERS)
5TRANSITION_VIEW (view_name = LOADING)
6TRANSITION_VIEW (view_name = CONNECTED)
7HANDOFF
8onSuccess (verification_status: pending_manual_verification)

When a user goes through the Same Day micro-deposits flow with Reroute to Credentials, you will additionally see TRANSITION_VIEW (view_name = NUMBERS_SELECT_INSTITUTION) with view_variant = SINGLE_INSTITUTION or view_variant = MULTI_INSTITUTION.

1OPEN (view_name = CONSENT)
2TRANSITION_VIEW (view_name = SELECT_INSTITUTION)
3SEARCH_INSTITUTION
4TRANSITION_VIEW (view_name = NUMBERS)
5TRANSITION_VIEW (view_name = NUMBERS_SELECT_INSTITUTION, view_variant = SINGLE_INSTITUTION)
6TRANSITION_VIEW (view_name = LOADING)
7TRANSITION_VIEW (view_name = CONNECTED)
8HANDOFF
9onSuccess (verification_status: pending_manual_verification)

When a user goes through the Same Day micro-deposits flow with the Auth Type Select configuration, you will additionally see TRANSITION_VIEW (view_name = SELECT_AUTH_TYPE) and also SELECT_AUTH_TYPE (selection = flow_type_manual)

1OPEN (view_name = CONSENT)
2TRANSITION_VIEW (view_name = SELECT_AUTH_TYPE)
3SELECT_AUTH_TYPE (selection = flow_type_manual)
4TRANSITION_VIEW (view_name = NUMBERS)
5TRANSITION_VIEW (view_name = LOADING)
6TRANSITION_VIEW (view_name = CONNECTED)
7HANDOFF
8onSuccess (verification_status: pending_manual_verification)

virtual accounts refunds

Refunds

Refund a Payment Initiation payment

Refunds enable you to refund your end users. You can issue refunds for any Payment Initiation payments that have settled in your virtual account.

  • The original payment must be in a settled state to be refunded.

  • To refund partially, specify the amount as part of the request.

  • If the amount is not specified, the refund amount will be equal to all of the remaining payment amount that has not been refunded yet.

  • If the remaining payment amount is less than one unit of currency (e.g. 1 GBP or 1 EUR), the refund will fail.

Execute a Refund

Make sure your virtual account is set up before following these steps. For more information on setting up an account, see Managing virtual accounts.

  1. Follow the Payment Confirmation flow to pay into your virtual account.

  2. Call /wallet/get to check your virtual account balance for sufficient funds.

  3. Issue a refund by calling /payment_initiation/payment/reverse, providing the payment_id from the payment made in Step 3, and optionally an amount for partial refunds. Store the refund_id and status from the response.

    • If you have configured transaction webhooks, you will receive a status update that the Refund transitioned from INITIATED to EXECUTED.

    • Alternatively, if not using webhooks, you can confirm the transaction has been executed by calling /wallet/transaction/get with the transaction_id.

    • You can also confirm that the original payment was refunded by calling /payment_initiation/payment/get with the payment_id to see the refund_id as part of the payment’s details.

  4. If you have previously executed any partial refunds for the payment, you can still issue subsequent refunds if this payment has sufficient remaining amount.

    • To check if the payment has sufficient remaining amount, call /payment_initiation/payment/get and fetch the amount_refunded field, which represents the amount that has been refunded already. Subtract this from the payment amount to calculate the amount still available to refund.

A successful refund will transition to the EXECUTED status. If a refund is in a FAILED status, you may try again, with a new idempotency_key, until you have a refund in an EXECUTED status for the payment. Refunds should transition to EXECUTED or FAILED automatically. If this does not occur,

Testing Refunds

You can begin testing Refunds in Sandbox by following the steps listed in the Add Virtual Accounts to your App guide. For Production access you will first need to submit a product access request Support ticket.

auth coverage instant

Instant Auth & Instant Match

Learn how to authenticate your users instantly

Instant Auth

Instant Auth supports more than 3,800 financial institutions with credential-based login. Instant Auth is the default Auth flow and does not require extra configuration steps if Auth is already configured in your app. For clarity and completeness, the section below explains how to configure Instant Auth.

Instant Auth Link flow

You can try out the Instant Match flow in Link Demo. See more details in our testing guide.

Configure & Create a link_token

Create a link_token with the following parameters:

  • products array containing auth – If you are using only auth and no other products, auth must be specified in the Products array. Other products (such as identity) may be specified as well. If you are using multiple products, auth is not required to be specified in the products array, but including it is recommended for the best user experience.
Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Initialize Link with a link_token

After creating a link_token for the auth product, use it to initialize Plaid Link.

When the user inputs their username and password for the financial institution, the onSuccess() callback function will return a public_token.

Select Language
1Plaid.create({
2  // Fetch a link_token configured for 'auth' from your app server
3  token: (await $.post('/create_link_token')).link_token,
4  onSuccess: (public_token, metadata) => {
5    // Send the public_token and accounts to your app server
6    $.post('/exchange_public_token', {
7      publicToken: public_token,
8      accounts: metadata.accounts,
9    });
10  },
11});
Exchange the public_token and fetch Auth data

In your own backend server, call the /item/public_token/exchange endpoint with the Link public_token received in the onSuccess callback to obtain an access_token. Persist the returned access_token and item_id in your database in relation to the user. You will use the access_token when making requests to the /auth/get endpoint.

Select group for content switcher
Select Language
1const publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d';
2
3try {
4  // Obtain an access_token from the Link public_token
5  const tokenResponse = await client.itemPublicTokenExchange({
6      public_token: publicToken}),
7  const accessToken = tokenResponse.access_token;
8
9  // Instantly fetch Auth numbers
10  const request: AuthGetRequest = {
11    access_token: accessToken,
12  };
13  const response = await plaidClient.authGet(request);
14  const numbers = response.numbers;
15} catch (err) {
16  // handle error
17}

Check out the /auth/get API reference documentation to see the full Auth request and response schema.

1{
2  "numbers": {
3    "ach": [
4      {
5        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
6        "account": "9900009606",
7        "routing": "011401533",
8        "wire_routing": "021000021"
9      }
10    ],
11    "eft": [],
12    "international": [],
13    "bacs": []
14  },
15  "accounts": [{ Object }],
16  "item": { Object },
17  "request_id": "m8MDnv9okwxFNBV"
18}

Instant Match

Instant Match is available for approximately 1,500 U.S. additional financial institutions where Instant Auth is not available. Instant Match is enabled automatically for Auth customers and is automatically provided at supported institutions as a fallback experience when Instant Auth is not available. When using Instant Match, Plaid Link will prompt your user to enter their account number and routing number for a depository account. Plaid will then verify the last four digits of the user-provided account number against the account mask retrieved from the financial institution.

You can try out the Instant Match flow in Link Demo. See more details in our testing guide.

When using the Instant Match flow, the user can verify only a single account. Even if the Account Select properties allow selecting all or multiple accounts, the ability to select multiple depository accounts for Auth will be disabled in Link if the institution is using the Instant Match flow.

Configuring in Link

Instant Match will be enabled automatically if you configure the link_token with the following parameters:

  • add "auth" to products array
  • country_codes set to ['US'] (adding any other countries to the array will disable Instant Match)

Optionally, you can disable Instant Match on a per-session basis via the /link/token/create call, by setting "auth.instant_match_enabled": false in the request body. If you would like to disable Instant Match automatically for all Link sessions, contact your Account Manager or file a support ticket via the Dashboard.

Select Language
1const request: LinkTokenCreateRequest = {
2  user: { client_user_id: new Date().getTime().toString() },
3  client_name: 'Plaid App',
4  products: [Products.Auth],
5  country_codes: [CountryCode.Us],
6  language: 'en',
7};
8try {
9  const response = await plaidClient.linkTokenCreate(request);
10  const linkToken = response.data.link_token;
11} catch (error) {
12    // handle error
13}
Handling Link events

For a user who goes through the Instant Match flow, the TRANSITION_VIEW (view_name = NUMBERS) event will occur after SUBMIT_CREDENTIALS, and in the onSuccess callback the verification_status will be null because the user would have been verified instantly.

1OPEN (view_name = CONSENT)
2TRANSITION_VIEW view_name = SELECT_INSTITUTION)
3SEARCH_INSTITUTION
4SELECT_INSTITUTION
5TRANSITION_VIEW (view_name = CREDENTIAL)
6SUBMIT_CREDENTIALS
7TRANSITION_VIEW (view_name = LOADING)
8TRANSITION_VIEW (view_name = MFA, mfa_type = code)
9SUBMIT_MFA (mfa_type = code)
10TRANSITION_VIEW (view_name = LOADING)
11TRANSITION_VIEW (view_name = SELECT_ACCOUNT)
12TRANSITION_VIEW (view_name = NUMBERS)
13TRANSITION_VIEW (view_name = LOADING)
14TRANSITION_VIEW (view_name = CONNECTED)
15HANDOFF
16onSuccess (verification_status: null)

api institutions

Institutions endpoints

Fetch data about supported institutions

The interface for these endpoints has changed in a recent API release. If you are using an API version prior to 2020-09-14, see API versioning.

Introduction

Institutions endpoints support querying all institutions, as well as looking up a single institution to retrieve up-to-date information about its health status and capabilities. This can be useful for apps whose business logic may depend on institution capabilities, such as Payment Initiation. API-provided institution health data can also be used for in-app UIs. For example, Personal Financial Management (PFM) apps can help set user expectations around data availability by showing dashboard data displaying the health of a user's connected institutions, in conjunction with personalized Item last updated data from /item/get.

For non-programmatic access to institution information, the status dashboard provides a browsable view of institutions, supported products, and institution health.

Institution coverage

To see which institutions are supported, or to look up the status of a specific institution, use the Institution status dashboard. You can also query this information programmatically via the /institutions/get and /institutions/search endpoints.

To see which institutions support a particular product, use /institutions/get and specify the product in the options.products array.

Plaid supports over 12,000 institutions across North America and Europe.

By default, you receive access to institutions in all countries in Sandbox and Development, and to United States and Canada in Production. To gain access to additional countries in Production, file a product access Support ticket.

For a list of which products are supported for each country, see Global coverage.

Endpoints
/institutions/getGet a list of all supported institutions meeting specified criteria
/institutions/get_by_idGet details about a specific institution
/institutions/searchLook up an institution by name

/institutions/get

Get details of all supported institutions

Returns a JSON response containing details on all financial institutions currently supported by Plaid. Because Plaid supports thousands of institutions, results are paginated.
If there is no overlap between an institution’s enabled products and a client’s enabled products, then the institution will be filtered out from the response. As a result, the number of institutions returned may not match the count specified in the call.

institutions/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
count
requiredinteger
The total number of Institutions to return.

Minimum: 1
Maximum: 500
offset
requiredinteger
The number of Institutions to skip.

Minimum: 0
country_codes
required[string]
Specify which country or countries to include institutions from, using the ISO-3166-1 alpha-2 country code standard.
In API versions 2019-05-29 and earlier, the country_codes parameter is an optional parameter within the options object and will default to [US] if it is not supplied.

Min items: 1
Possible values: US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT
options
object
An optional object to filter /institutions/get results.
products
[string]
Filter the Institutions based on which products they support.

Min items: 1
Possible values: assets, auth, balance, employment, identity, income_verification, identity_verification, investments, liabilities, payment_initiation, standing_orders, transactions, transfer
routing_numbers
[string]
Specify an array of routing numbers to filter institutions. The response will only return institutions that match all of the routing numbers in the array. Routing number records used for this matching are not comprehensive; failure to match a given routing number to an institution does not mean that the institution is unsupported by Plaid.
oauth
boolean
Limit results to institutions with or without OAuth login flows. Note that institutions will have oauth set to true if some Items associated with that institution are required to use OAuth flows; institutions in a state of migration to OAuth will have the oauth attribute set to true.
include_optional_metadata
boolean
When true, return the institution's homepage URL, logo and primary brand color.
Note that Plaid does not own any of the logos shared by the API, and that by accessing or using these logos, you agree that you are doing so at your own risk and will, if necessary, obtain all required permissions from the appropriate rights holders and adhere to any applicable usage guidelines. Plaid disclaims all express or implied warranties with respect to the logos.
include_auth_metadata
boolean
When true, returns metadata related to the Auth product indicating which auth methods are supported.

Default: false
include_payment_initiation_metadata
boolean
When true, returns metadata related to the Payment Initiation product indicating which payment configurations are supported.

Default: false
Select group for content switcher
Select Language
1// Pull institutions
2const request: InstitutionsGetRequest = {
3  count: 10,
4  offset: 0,
5  country_codes: ['US'],
6};
7try {
8  const response = await plaidClient.institutionsGet(request);
9  const institutions = response.data.institutions;
10} catch (error) {
11  // Handle error
12}
institutions/get

Response fields and example

institutions
[object]
A list of Plaid institutions
institution_id
string
Unique identifier for the institution. Note that the same institution may have multiple records, each with different institution IDs; for example, if the institution has migrated to OAuth, there may be separate institution_ids for the OAuth and non-OAuth versions of the institution. Institutions that operate in different countries or with multiple login portals may also have separate institution_ids for each country or portal.
name
string
The official name of the institution.
products
[string]
A list of the Plaid products supported by the institution. Note that only institutions that support Instant Auth will return auth in the product array; institutions that do not list auth may still support other Auth methods such as Instant Match or Automated Micro-deposit Verification. To identify institutions that support those methods, use the auth_metadata object. For more details, see Full Auth coverage.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
country_codes
[string]
A list of the country codes supported by the institution.

Possible values: US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT
url
nullablestring
The URL for the institution's website
primary_color
nullablestring
Hexadecimal representation of the primary color used by the institution
logo
nullablestring
Base64 encoded representation of the institution's logo, returned as a base64 encoded 152x152 PNG. Not all institutions' logos are available.
routing_numbers
[string]
A partial list of routing numbers associated with the institution. This list is provided for the purpose of looking up institutions by routing number. It is not comprehensive and should never be used as a complete list of routing numbers for an institution.
dtc_numbers
[string]
A partial list of DTC numbers associated with the institution.
oauth
boolean
Indicates that the institution has an OAuth login flow. This will be true if OAuth is supported for any Items associated with the institution, even if the institution also supports non-OAuth connections.
status
nullableobject
The status of an institution is determined by the health of its Item logins, Transactions updates, Investments updates, Liabilities updates, Auth requests, Balance requests, Identity requests, Investments requests, and Liabilities requests. A login attempt is conducted during the initial Item add in Link. If there is not enough traffic to accurately calculate an institution's status, Plaid will return null rather than potentially inaccurate data.
Institution status is accessible in the Dashboard and via the API using the /institutions/get_by_id endpoint with the include_status option set to true. Note that institution status is not available in the Sandbox environment.
item_logins
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
transactions_updates
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
auth
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
identity
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
investments_updates
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
liabilities_updates
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
liabilities
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
investments
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
health_incidents
nullable[object]
Details of recent health incidents associated with the institution.
start_date
string
The start date of the incident, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".

Format: date-time
end_date
nullablestring
The end date of the incident, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".

Format: date-time
title
string
The title of the incident
incident_updates
[object]
Updates on the health incident.
description
string
The content of the update.
status
string
The status of the incident.

Possible values: INVESTIGATING, IDENTIFIED, SCHEDULED, RESOLVED, UNKNOWN
updated_date
string
The date when the update was published, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".

Format: date-time
payment_initiation_metadata
nullableobject
Metadata that captures what specific payment configurations an institution supports when making Payment Initiation requests.
supports_international_payments
boolean
Indicates whether the institution supports payments from a different country.
supports_sepa_instant
boolean
Indicates whether the institution supports SEPA Instant payments.
maximum_payment_amount
object
A mapping of currency to maximum payment amount (denominated in the smallest unit of currency) supported by the institution.
Example: {"GBP": "10000"}
supports_refund_details
boolean
Indicates whether the institution supports returning refund details when initiating a payment.
standing_order_metadata
nullableobject
Metadata specifically related to valid Payment Initiation standing order configurations for the institution.
supports_standing_order_end_date
boolean
Indicates whether the institution supports closed-ended standing orders by providing an end date.
supports_standing_order_negative_execution_days
boolean
This is only applicable to MONTHLY standing orders. Indicates whether the institution supports negative integers (-1 to -5) for setting up a MONTHLY standing order relative to the end of the month.
valid_standing_order_intervals
[string]
A list of the valid standing order intervals supported by the institution.

Possible values: WEEKLY, MONTHLY
Min length: 1
auth_metadata
nullableobject
Metadata that captures information about the Auth features of an institution.
supported_methods
nullableobject
Metadata specifically related to which auth methods an institution supports.
instant_auth
boolean
Indicates if instant auth is supported.
instant_match
boolean
Indicates if instant match is supported.
automated_micro_deposits
boolean
Indicates if automated microdeposits are supported.
total
integer
The total number of institutions available via this endpoint
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "institutions": [
3    {
4      "country_codes": [
5        "US"
6      ],
7      "institution_id": "ins_1",
8      "name": "Bank of America",
9      "products": [
10        "assets",
11        "auth",
12        "balance",
13        "transactions",
14        "identity",
15        "liabilities"
16      ],
17      "routing_numbers": [
18        "011000138",
19        "011200365",
20        "011400495"
21      ],
22      "dtc_numbers": [
23        "2236",
24        "0955",
25        "1367"
26      ],
27      "oauth": false,
28      "status": {
29        "item_logins": {
30          "status": "HEALTHY",
31          "last_status_change": "2019-02-15T15:53:00Z",
32          "breakdown": {
33            "success": 0.9,
34            "error_plaid": 0.01,
35            "error_institution": 0.09
36          }
37        },
38        "transactions_updates": {
39          "status": "HEALTHY",
40          "last_status_change": "2019-02-12T08:22:00Z",
41          "breakdown": {
42            "success": 0.95,
43            "error_plaid": 0.02,
44            "error_institution": 0.03,
45            "refresh_interval": "NORMAL"
46          }
47        },
48        "auth": {
49          "status": "HEALTHY",
50          "last_status_change": "2019-02-15T15:53:00Z",
51          "breakdown": {
52            "success": 0.91,
53            "error_plaid": 0.01,
54            "error_institution": 0.08
55          }
56        },
57        "identity": {
58          "status": "DEGRADED",
59          "last_status_change": "2019-02-15T15:50:00Z",
60          "breakdown": {
61            "success": 0.42,
62            "error_plaid": 0.08,
63            "error_institution": 0.5
64          }
65        },
66        "investments": {
67          "status": "HEALTHY",
68          "last_status_change": "2019-02-15T15:53:00Z",
69          "breakdown": {
70            "success": 0.89,
71            "error_plaid": 0.02,
72            "error_institution": 0.09
73          },
74          "liabilities": {
75            "status": "HEALTHY",
76            "last_status_change": "2019-02-15T15:53:00Z",
77            "breakdown": {
78              "success": 0.89,
79              "error_plaid": 0.02,
80              "error_institution": 0.09
81            }
82          }
83        },
84        "investments_updates": {
85          "status": "HEALTHY",
86          "last_status_change": "2019-02-12T08:22:00Z",
87          "breakdown": {
88            "success": 0.95,
89            "error_plaid": 0.02,
90            "error_institution": 0.03,
91            "refresh_interval": "NORMAL"
92          }
93        },
94        "liabilities_updates": {
95          "status": "HEALTHY",
96          "last_status_change": "2019-02-12T08:22:00Z",
97          "breakdown": {
98            "success": 0.95,
99            "error_plaid": 0.02,
100            "error_institution": 0.03,
101            "refresh_interval": "NORMAL"
102          }
103        }
104      }
105    }
106  ],
107  "request_id": "tbFyCEqkU774ZGG",
108  "total": 11384
109}
Was this helpful?

/institutions/get_by_id

Get details of an institution

Returns a JSON response containing details on a specified financial institution currently supported by Plaid.
Versioning note: API versions 2019-05-29 and earlier allow use of the public_key parameter instead of the client_id and secret to authenticate to this endpoint. The public_key has been deprecated; all customers are encouraged to use client_id and secret instead.

institutions/get_by_id

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
institution_id
requiredstring
The ID of the institution to get details about

Min length: 1
country_codes
required[string]
Specify which country or countries to include institutions from, using the ISO-3166-1 alpha-2 country code standard. In API versions 2019-05-29 and earlier, the country_codes parameter is an optional parameter within the options object and will default to [US] if it is not supplied.

Possible values: US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT
options
object
Specifies optional parameters for /institutions/get_by_id. If provided, must not be null.
include_optional_metadata
boolean
When true, return an institution's logo, brand color, and URL. When available, the bank's logo is returned as a base64 encoded 152x152 PNG, the brand color is in hexadecimal format. The default value is false.
Note that Plaid does not own any of the logos shared by the API and that by accessing or using these logos, you agree that you are doing so at your own risk and will, if necessary, obtain all required permissions from the appropriate rights holders and adhere to any applicable usage guidelines. Plaid disclaims all express or implied warranties with respect to the logos.

Default: false
include_status
boolean
If true, the response will include status information about the institution. Default value is false.

Default: false
include_auth_metadata
boolean
When true, returns metadata related to the Auth product indicating which auth methods are supported.

Default: false
include_payment_initiation_metadata
boolean
When true, returns metadata related to the Payment Initiation product indicating which payment configurations are supported.

Default: false
Select group for content switcher
Select Language
1const request: InstitutionsGetByIdRequest = {
2  institution_id: institutionID,
3  country_codes: ['US'],
4};
5try {
6  const response = await plaidClient.institutionsGetById(request);
7  const institution = response.data.institution;
8} catch (error) {
9  // Handle error
10}
institutions/get_by_id

Response fields and example

institution
object
Details relating to a specific financial institution
institution_id
string
Unique identifier for the institution. Note that the same institution may have multiple records, each with different institution IDs; for example, if the institution has migrated to OAuth, there may be separate institution_ids for the OAuth and non-OAuth versions of the institution. Institutions that operate in different countries or with multiple login portals may also have separate institution_ids for each country or portal.
name
string
The official name of the institution.
products
[string]
A list of the Plaid products supported by the institution. Note that only institutions that support Instant Auth will return auth in the product array; institutions that do not list auth may still support other Auth methods such as Instant Match or Automated Micro-deposit Verification. To identify institutions that support those methods, use the auth_metadata object. For more details, see Full Auth coverage.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
country_codes
[string]
A list of the country codes supported by the institution.

Possible values: US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT
url
nullablestring
The URL for the institution's website
primary_color
nullablestring
Hexadecimal representation of the primary color used by the institution
logo
nullablestring
Base64 encoded representation of the institution's logo, returned as a base64 encoded 152x152 PNG. Not all institutions' logos are available.
routing_numbers
[string]
A partial list of routing numbers associated with the institution. This list is provided for the purpose of looking up institutions by routing number. It is not comprehensive and should never be used as a complete list of routing numbers for an institution.
dtc_numbers
[string]
A partial list of DTC numbers associated with the institution.
oauth
boolean
Indicates that the institution has an OAuth login flow. This will be true if OAuth is supported for any Items associated with the institution, even if the institution also supports non-OAuth connections.
status
nullableobject
The status of an institution is determined by the health of its Item logins, Transactions updates, Investments updates, Liabilities updates, Auth requests, Balance requests, Identity requests, Investments requests, and Liabilities requests. A login attempt is conducted during the initial Item add in Link. If there is not enough traffic to accurately calculate an institution's status, Plaid will return null rather than potentially inaccurate data.
Institution status is accessible in the Dashboard and via the API using the /institutions/get_by_id endpoint with the include_status option set to true. Note that institution status is not available in the Sandbox environment.
item_logins
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
transactions_updates
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
auth
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
identity
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
investments_updates
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
liabilities_updates
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
liabilities
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
investments
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
health_incidents
nullable[object]
Details of recent health incidents associated with the institution.
start_date
string
The start date of the incident, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".

Format: date-time
end_date
nullablestring
The end date of the incident, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".

Format: date-time
title
string
The title of the incident
incident_updates
[object]
Updates on the health incident.
description
string
The content of the update.
status
string
The status of the incident.

Possible values: INVESTIGATING, IDENTIFIED, SCHEDULED, RESOLVED, UNKNOWN
updated_date
string
The date when the update was published, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".

Format: date-time
payment_initiation_metadata
nullableobject
Metadata that captures what specific payment configurations an institution supports when making Payment Initiation requests.
supports_international_payments
boolean
Indicates whether the institution supports payments from a different country.
supports_sepa_instant
boolean
Indicates whether the institution supports SEPA Instant payments.
maximum_payment_amount
object
A mapping of currency to maximum payment amount (denominated in the smallest unit of currency) supported by the institution.
Example: {"GBP": "10000"}
supports_refund_details
boolean
Indicates whether the institution supports returning refund details when initiating a payment.
standing_order_metadata
nullableobject
Metadata specifically related to valid Payment Initiation standing order configurations for the institution.
supports_standing_order_end_date
boolean
Indicates whether the institution supports closed-ended standing orders by providing an end date.
supports_standing_order_negative_execution_days
boolean
This is only applicable to MONTHLY standing orders. Indicates whether the institution supports negative integers (-1 to -5) for setting up a MONTHLY standing order relative to the end of the month.
valid_standing_order_intervals
[string]
A list of the valid standing order intervals supported by the institution.

Possible values: WEEKLY, MONTHLY
Min length: 1
auth_metadata
nullableobject
Metadata that captures information about the Auth features of an institution.
supported_methods
nullableobject
Metadata specifically related to which auth methods an institution supports.
instant_auth
boolean
Indicates if instant auth is supported.
instant_match
boolean
Indicates if instant match is supported.
automated_micro_deposits
boolean
Indicates if automated microdeposits are supported.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "institution": {
3    "country_codes": [
4      "US"
5    ],
6    "institution_id": "ins_109512",
7    "name": "Houndstooth Bank",
8    "products": [
9      "auth",
10      "balance",
11      "identity",
12      "transactions"
13    ],
14    "routing_numbers": [
15      "011000138",
16      "011200365",
17      "011400495"
18    ],
19    "dtc_numbers": [
20      "2236",
21      "0955",
22      "1367"
23    ],
24    "oauth": false,
25    "status": {
26      "item_logins": {
27        "status": "HEALTHY",
28        "last_status_change": "2019-02-15T15:53:00Z",
29        "breakdown": {
30          "success": 0.9,
31          "error_plaid": 0.01,
32          "error_institution": 0.09
33        }
34      },
35      "transactions_updates": {
36        "status": "HEALTHY",
37        "last_status_change": "2019-02-12T08:22:00Z",
38        "breakdown": {
39          "success": 0.95,
40          "error_plaid": 0.02,
41          "error_institution": 0.03,
42          "refresh_interval": "NORMAL"
43        }
44      },
45      "auth": {
46        "status": "HEALTHY",
47        "last_status_change": "2019-02-15T15:53:00Z",
48        "breakdown": {
49          "success": 0.91,
50          "error_plaid": 0.01,
51          "error_institution": 0.08
52        }
53      },
54      "identity": {
55        "status": "DEGRADED",
56        "last_status_change": "2019-02-15T15:50:00Z",
57        "breakdown": {
58          "success": 0.42,
59          "error_plaid": 0.08,
60          "error_institution": 0.5
61        }
62      },
63      "investments": {
64        "status": "HEALTHY",
65        "last_status_change": "2019-02-15T15:53:00Z",
66        "breakdown": {
67          "success": 0.89,
68          "error_plaid": 0.02,
69          "error_institution": 0.09
70        },
71        "liabilities": {
72          "status": "HEALTHY",
73          "last_status_change": "2019-02-15T15:53:00Z",
74          "breakdown": {
75            "success": 0.89,
76            "error_plaid": 0.02,
77            "error_institution": 0.09
78          }
79        }
80      },
81      "investments_updates": {
82        "status": "HEALTHY",
83        "last_status_change": "2019-02-12T08:22:00Z",
84        "breakdown": {
85          "success": 0.95,
86          "error_plaid": 0.02,
87          "error_institution": 0.03,
88          "refresh_interval": "NORMAL"
89        }
90      },
91      "liabilities_updates": {
92        "status": "HEALTHY",
93        "last_status_change": "2019-02-12T08:22:00Z",
94        "breakdown": {
95          "success": 0.95,
96          "error_plaid": 0.02,
97          "error_institution": 0.03,
98          "refresh_interval": "NORMAL"
99        }
100      }
101    },
102    "primary_color": "#004966",
103    "url": "https://plaid.com",
104    "logo": null
105  },
106  "request_id": "m8MDnv9okwxFNBV"
107}
Was this helpful?

/institutions/search

Search institutions

Returns a JSON response containing details for institutions that match the query parameters, up to a maximum of ten institutions per query.
Versioning note: API versions 2019-05-29 and earlier allow use of the public_key parameter instead of the client_id and secret parameters to authenticate to this endpoint. The public_key parameter has since been deprecated; all customers are encouraged to use client_id and secret instead.

institutions/search

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
query
requiredstring
The search query. Institutions with names matching the query are returned

Min length: 1
products
required[string]
Filter the Institutions based on whether they support all products listed in products. Provide null to get institutions regardless of supported products. Note that when auth is specified as a product, if you are enabled for Instant Match or Automated Micro-deposits, institutions that support those products will be returned even if auth is not present in their product array.

Min items: 1
Possible values: assets, auth, balance, employment, identity, income_verification, investments, liabilities, identity_verification, payment_initiation, standing_orders, transactions, transfer
country_codes
required[string]
Specify which country or countries to include institutions from, using the ISO-3166-1 alpha-2 country code standard. In API versions 2019-05-29 and earlier, the country_codes parameter is an optional parameter within the options object and will default to [US] if it is not supplied.

Possible values: US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT
options
object
An optional object to filter /institutions/search results.
oauth
boolean
Limit results to institutions with or without OAuth login flows. Note that institutions will have oauth set to true if some Items associated with that institution are required to use OAuth flows; institutions in a state of migration to OAuth will have the oauth attribute set to true.
include_optional_metadata
boolean
When true, return the institution's homepage URL, logo and primary brand color.
include_auth_metadata
boolean
When true, returns metadata related to the Auth product indicating which auth methods are supported.

Default: false
include_payment_initiation_metadata
boolean
When true, returns metadata related to the Payment Initiation product indicating which payment configurations are supported.

Default: false
payment_initiation
object
Additional options that will be used to filter institutions by various Payment Initiation configurations.
payment_id
string
A unique ID identifying the payment
consent_id
string
A unique ID identifying the payment consent
Select group for content switcher
Select Language
1const request: InstitutionsSearchRequest = {
2  query: institutionID,
3  products: ['transactions'],
4  country_codes: ['US'],
5};
6try {
7  const response = await plaidClient.institutionsSearch(request);
8  const institutions = response.data.institutions;
9} catch (error) {
10  // Handle error
11}
institutions/search

Response fields and example

institutions
[object]
An array of institutions matching the search criteria
institution_id
string
Unique identifier for the institution. Note that the same institution may have multiple records, each with different institution IDs; for example, if the institution has migrated to OAuth, there may be separate institution_ids for the OAuth and non-OAuth versions of the institution. Institutions that operate in different countries or with multiple login portals may also have separate institution_ids for each country or portal.
name
string
The official name of the institution.
products
[string]
A list of the Plaid products supported by the institution. Note that only institutions that support Instant Auth will return auth in the product array; institutions that do not list auth may still support other Auth methods such as Instant Match or Automated Micro-deposit Verification. To identify institutions that support those methods, use the auth_metadata object. For more details, see Full Auth coverage.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
country_codes
[string]
A list of the country codes supported by the institution.

Possible values: US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT
url
nullablestring
The URL for the institution's website
primary_color
nullablestring
Hexadecimal representation of the primary color used by the institution
logo
nullablestring
Base64 encoded representation of the institution's logo, returned as a base64 encoded 152x152 PNG. Not all institutions' logos are available.
routing_numbers
[string]
A partial list of routing numbers associated with the institution. This list is provided for the purpose of looking up institutions by routing number. It is not comprehensive and should never be used as a complete list of routing numbers for an institution.
dtc_numbers
[string]
A partial list of DTC numbers associated with the institution.
oauth
boolean
Indicates that the institution has an OAuth login flow. This will be true if OAuth is supported for any Items associated with the institution, even if the institution also supports non-OAuth connections.
status
nullableobject
The status of an institution is determined by the health of its Item logins, Transactions updates, Investments updates, Liabilities updates, Auth requests, Balance requests, Identity requests, Investments requests, and Liabilities requests. A login attempt is conducted during the initial Item add in Link. If there is not enough traffic to accurately calculate an institution's status, Plaid will return null rather than potentially inaccurate data.
Institution status is accessible in the Dashboard and via the API using the /institutions/get_by_id endpoint with the include_status option set to true. Note that institution status is not available in the Sandbox environment.
item_logins
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
transactions_updates
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
auth
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
identity
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
investments_updates
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
liabilities_updates
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
liabilities
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
investments
nullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
status
deprecatedstring
This field is deprecated in favor of the breakdown object, which provides more granular institution health data.
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing

Possible values: HEALTHY, DEGRADED, DOWN
last_status_change
string
ISO 8601 formatted timestamp of the last status change for the institution.

Format: date-time
breakdown
object
A detailed breakdown of the institution's performance for a request type. The values for success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.
success
number
The percentage of login attempts that are successful, expressed as a decimal.

Format: double
error_plaid
number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.

Format: double
error_institution
number
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.

Format: double
refresh_interval
string
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.

Possible values: NORMAL, DELAYED, STOPPED
health_incidents
nullable[object]
Details of recent health incidents associated with the institution.
start_date
string
The start date of the incident, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".

Format: date-time
end_date
nullablestring
The end date of the incident, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".

Format: date-time
title
string
The title of the incident
incident_updates
[object]
Updates on the health incident.
description
string
The content of the update.
status
string
The status of the incident.

Possible values: INVESTIGATING, IDENTIFIED, SCHEDULED, RESOLVED, UNKNOWN
updated_date
string
The date when the update was published, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".

Format: date-time
payment_initiation_metadata
nullableobject
Metadata that captures what specific payment configurations an institution supports when making Payment Initiation requests.
supports_international_payments
boolean
Indicates whether the institution supports payments from a different country.
supports_sepa_instant
boolean
Indicates whether the institution supports SEPA Instant payments.
maximum_payment_amount
object
A mapping of currency to maximum payment amount (denominated in the smallest unit of currency) supported by the institution.
Example: {"GBP": "10000"}
supports_refund_details
boolean
Indicates whether the institution supports returning refund details when initiating a payment.
standing_order_metadata
nullableobject
Metadata specifically related to valid Payment Initiation standing order configurations for the institution.
supports_standing_order_end_date
boolean
Indicates whether the institution supports closed-ended standing orders by providing an end date.
supports_standing_order_negative_execution_days
boolean
This is only applicable to MONTHLY standing orders. Indicates whether the institution supports negative integers (-1 to -5) for setting up a MONTHLY standing order relative to the end of the month.
valid_standing_order_intervals
[string]
A list of the valid standing order intervals supported by the institution.

Possible values: WEEKLY, MONTHLY
Min length: 1
auth_metadata
nullableobject
Metadata that captures information about the Auth features of an institution.
supported_methods
nullableobject
Metadata specifically related to which auth methods an institution supports.
instant_auth
boolean
Indicates if instant auth is supported.
instant_match
boolean
Indicates if instant match is supported.
automated_micro_deposits
boolean
Indicates if automated microdeposits are supported.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "institutions": [
3    {
4      "country_codes": [
5        "US"
6      ],
7      "institution_id": "ins_118923",
8      "name": "Red Platypus Bank - Red Platypus Bank",
9      "products": [
10        "assets",
11        "auth",
12        "balance",
13        "transactions",
14        "identity"
15      ],
16      "routing_numbers": [
17        "011000138",
18        "011200365",
19        "011400495"
20      ],
21      "dtc_numbers": [
22        "2236",
23        "0955",
24        "1367"
25      ],
26      "oauth": false,
27      "status": {
28        "item_logins": {
29          "status": "HEALTHY",
30          "last_status_change": "2019-02-15T15:53:00Z",
31          "breakdown": {
32            "success": 0.9,
33            "error_plaid": 0.01,
34            "error_institution": 0.09
35          }
36        },
37        "transactions_updates": {
38          "status": "HEALTHY",
39          "last_status_change": "2019-02-12T08:22:00Z",
40          "breakdown": {
41            "success": 0.95,
42            "error_plaid": 0.02,
43            "error_institution": 0.03,
44            "refresh_interval": "NORMAL"
45          }
46        },
47        "auth": {
48          "status": "HEALTHY",
49          "last_status_change": "2019-02-15T15:53:00Z",
50          "breakdown": {
51            "success": 0.91,
52            "error_plaid": 0.01,
53            "error_institution": 0.08
54          }
55        },
56        "identity": {
57          "status": "DEGRADED",
58          "last_status_change": "2019-02-15T15:50:00Z",
59          "breakdown": {
60            "success": 0.42,
61            "error_plaid": 0.08,
62            "error_institution": 0.5
63          }
64        },
65        "investments": {
66          "status": "HEALTHY",
67          "last_status_change": "2019-02-15T15:53:00Z",
68          "breakdown": {
69            "success": 0.89,
70            "error_plaid": 0.02,
71            "error_institution": 0.09
72          },
73          "liabilities": {
74            "status": "HEALTHY",
75            "last_status_change": "2019-02-15T15:53:00Z",
76            "breakdown": {
77              "success": 0.89,
78              "error_plaid": 0.02,
79              "error_institution": 0.09
80            }
81          }
82        },
83        "investments_updates": {
84          "status": "HEALTHY",
85          "last_status_change": "2019-02-12T08:22:00Z",
86          "breakdown": {
87            "success": 0.95,
88            "error_plaid": 0.02,
89            "error_institution": 0.03,
90            "refresh_interval": "NORMAL"
91          }
92        },
93        "liabilities_updates": {
94          "status": "HEALTHY",
95          "last_status_change": "2019-02-12T08:22:00Z",
96          "breakdown": {
97            "success": 0.95,
98            "error_plaid": 0.02,
99            "error_institution": 0.03,
100            "refresh_interval": "NORMAL"
101          }
102        }
103      }
104    }
105  ],
106  "request_id": "Ggmk0enW4smO2Tp"
107}
Was this helpful?

errors microdeposits

Micro-deposits Errors

Guide to troubleshooting micro-deposits errors

MICRODEPOSITS_UNSUPPORTED_ENVIRONMENT

Microdeposits not supported in Development
Common causes
  • Micro-deposit-based verification was attempted in the Development environment.
Troubleshooting steps
1http code 400
2{
3 "error_type": "MICRODEPOSITS_ERROR",
4 "error_code": "MICRODEPOSITS_UNSUPPORTED_ENVIRONMENT",
5 "error_message": "microdeposits is not supported on this environment",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

BANK_TRANSFER_ACCOUNT_BLOCKED

The bank transfer could not be completed because a previous transfer involving the same end-user account resulted in an error.
Common causes
  • Plaid cannot send micro-deposits to verify this account because it has flagged the account as not valid for use. This may happen, for example, because a previous attempt by Plaid to transfer funds to this end user account resulted in an "account frozen" or "invalid account number" error.
Troubleshooting steps
1http code 400
2{
3 "error_type": "BANK_TRANSFER_ERROR",
4 "error_code": "BANK_TRANSFER_ACCOUNT_BLOCKED",
5 "error_message": "bank transfer was blocked due to a previous ACH return on this account",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

transfer

Introduction to Transfer and Transfer UI

Intelligently process transfers between accounts

Overview

Transfer

Transfer enables developers to seamlessly initiate and manage bank-to-bank payments. Transfer makes ACH easy by providing a built-in authorization engine to minimize clawback of funds due to returns. All of this is accomplished with a simple set of APIs so you can get started with ACH quickly and easily.

Transfer is best suited for developers interested in building custom Nacha-compliant user interfaces that require full control of the transfer experience. For a simpler integration using a less customizable user experience, see Transfer UI.

Transfer is available only to senders and recipients within the US. To apply for Transfer, complete the Production access request form and select Transfer as a requested product. For more information, you can also contact Sales or, for existing customers, your Plaid Account Manager.

Transfer UI

Transfer UI is an intuitive user interface that enables end users to authorize transfers within your application. It is easy to integrate and fully handles the transfer execution experience for you. It also utilizes the same built-in authorization engine used by Transfer to minimize return risks.

Transfer UI is best suited for developers interested in quickly launching a payments interface that is easy to use.

Transfer process overview

The process below is for Transfer only. For the Transfer UI process overview, see Transfer UI.

  1. (Optional) Create a Payment Profile using /payment_profile/create and receive a payment_profile_token. While this step is optional, it is recommended to maximize conversion by allowing users to avoid re-entering payment information. We recommend using a Payment Profile if you are not using Transfer UI and do not need to use other Plaid Products with the Item you are creating. Payment Profiles cannot be used with Transfer UI.

  2. Call /link/token/create, specifying transfer in the products parameter. If using a payment profile, provide the payment_profile_token in the transfer.payment_profile_token field and the user's phone number in the user.phone_number field.

  3. Initialize a Link instance using the link_token created in the previous step. For more details for your specific platform, see the Link documentation.

  4. The user will now go through the Link flow. The onSuccess callback will indicate they have completed the Link flow.

  5. (If not using a Payment Profile) You will receive a public_token from the onSuccess callback. Call /item/public_token/exchange to exchange this public token for an access_token. You will also need to obtain the account id of the account you wish to transfer funds to or from; this can also be obtained from the onSuccess callback, within metadata.accounts, or by calling /accounts/get.

  6. Determine the transfer failure risk by calling /transfer/authorization/create and providing either the access_token and account_id pair, or the payment_profile_token. /transfer/authorization/create will return an authorization object.

  7. Check the authorization.decision. If it is declined, you cannot complete the transfer. If it is approved, check the authorization.decision_rationale field. If authorization.decision_rationale is null, proceed to the next step. If it is non-null, Plaid was unable to collect enough data to make a thorough risk evaluation; decide whether to proceed with creating the transfer based on your own risk assessment protocols.

  8. Create the transfer by calling /transfer/create using the authorization.id. Plaid will execute the transfer and automatically sweep funds into your account once they are available to be swept.

  9. (Optional) To monitor the progress of the sweep, use /transfer/sweep/list and/or /transfer/sweep/get. For more information, see Sweeping funds.

  10. (Optional) To monitor and sync transfer updates, use /transfer/list, /transfer/get, /transfer/event/list, and/or /transfer/event/sync. For more information, see Reconciling transfers.

Testing Transfer

Transfer is available only in the Sandbox and Production environments; it cannot be used in Development. You should automatically get access to Transfer in Sandbox after signing up for your free Plaid API keys. Transfer endpoints typically work the same in Sandbox as they do in Production; to get started with Transfer, see adding Transfer to your app. Plaid also offers a number of Sandbox-specific endpoints for testing Transfer; for more details, see the Sandbox API reference.

To request access to Transfer in Production, complete the Production access request form.

api processors

Processor endpoints

API reference for endpoints for use with or by Plaid partners

Processor token endpoints

Processor token endpoints are used to create tokens that are then sent to a Plaid partner for use in a Plaid integration. For a full list of integrations, see the developer dashboard. For specific information on Auth integrations, see Auth payment partners.

In this section
/processor/token/createCreate a processor token
/processor/stripe/bank_account_token/createCreate a bank account token for use with Stripe
/processor/token/permissions/setSet product permissions for a processor token
/processor/token/permissions/getGet product permissions for a processor token
/processor/token/webhook/updateSet the webhook URL for a processor token
See also
/sandbox/processor_token/createCreate a test Item and processor token (Sandbox only)

/processor/token/create

Create processor token

Used to create a token suitable for sending to one of Plaid's partners to enable integrations. Note that Stripe partnerships use bank account tokens instead; see /processor/stripe/bank_account_token/create for creating tokens for use with Stripe integrations. Once created, a processor token for a given Item cannot be modified or updated. If the account must be linked to a new or different partner resource, create a new Item by having the user go through the Link flow again; a new processor token can then be created from the new access_token. Processor tokens can also be revoked, using /item/remove.

processor/token/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
account_id
requiredstring
The account_id value obtained from the onSuccess callback in Link
processor
requiredstring
The processor you are integrating with.

Possible values: dwolla, galileo, modern_treasury, ocrolus, prime_trust, vesta, drivewealth, vopay, achq, check, checkbook, circle, sila_money, rize, svb_api, unit, wyre, lithic, alpaca, astra, moov, treasury_prime, marqeta, checkout, solid, highnote, gemini, apex_clearing, gusto, adyen, atomic, i2c, wepay, riskified, utb, adp_roll, fortress_trust, bond
Select group for content switcher
Select Language
1const {
2  Configuration,
3  PlaidApi,
4  PlaidEnvironments,
5  ProcessorTokenCreateRequest,
6} = require('plaid');
7// Change sandbox to development to test with live users;
8// Change to production when you're ready to go live!
9const configuration = new Configuration({
10  basePath: PlaidEnvironments.sandbox,
11  baseOptions: {
12    headers: {
13      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
14      'PLAID-SECRET': process.env.PLAID_SECRET,
15      'Plaid-Version': '2020-09-14',
16    },
17  },
18});
19
20const plaidClient = new PlaidApi(configuration);
21
22try {
23  // Exchange the public_token from Plaid Link for an access token.
24  const tokenResponse = await plaidClient.itemPublicTokenExchange({
25    public_token: PUBLIC_TOKEN,
26  });
27  const accessToken = tokenResponse.data.access_token;
28
29  // Create a processor token for a specific account id.
30  const request: ProcessorTokenCreateRequest = {
31    access_token: accessToken,
32    account_id: accountID,
33    processor: 'dwolla',
34  };
35  const processorTokenResponse = await plaidClient.processorTokenCreate(
36    request,
37  );
38  const processorToken = processorTokenResponse.data.processor_token;
39} catch (error) {
40  // handle error
41}
processor/token/create

Response fields and example

processor_token
string
The processor_token that can then be used by the Plaid partner to make API requests
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "xrQNYZ7Zoh6R7gV"
4}
Was this helpful?

/processor/token/permissions/set

Control a processor's access to products

Used to control a processor's access to products on the given processor token. By default, a processor will have access to all available products on the corresponding item. To restrict access to a particular set of products, call this endpoint with the desired products. To restore access to all available products, call this endpoint with an empty list. This endpoint can be called multiple times as your needs and your processor's needs change.

processor/token/permissions/set

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
processor_token
requiredstring
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor-<environment>-<identifier>
products
required[string]
A list of products the processor token should have access to. An empty list will grant access to all products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
Select Language
1try {
2  const request: ProcessorTokenPermissionsSetRequest = {
3    processor_token: processorToken,
4    products: ["auth", "balance", "identity"]
5  };
6  const response = await plaidClient.processorTokenPermissionsSet(
7    request,
8  );
9} catch (error) {
10  // handle error
11}
processor/token/permissions/set

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "xrQNYZ7Zoh6R7gV"
3}
Was this helpful?

/processor/token/permissions/get

Get a processor token's product permissions

Used to get a processor token's product permissions. The products field will be an empty list if the processor can access all available products.

processor/token/permissions/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
processor_token
requiredstring
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor-<environment>-<identifier>
Select Language
1try {
2  const request: ProcessorTokenPermissionsGetRequest = {
3    processor_token: processorToken,
4  };
5  const response = await plaidClient.processorTokenPermissionsGet(
6    request,
7  );
8  const products = response.data.products;
9} catch (error) {
10  // handle error
11}
processor/token/permissions/get

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
products
[string]
A list of products the processor token should have access to. An empty list means that the processor has access to all available products, including future products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
1{
2  "request_id": "xrQNYZ7Zoh6R7gV",
3  "products": [
4    "auth",
5    "balance",
6    "identity"
7  ]
8}
Was this helpful?

/processor/token/webhook/update

Update a processor token's webhook URL

This endpoint allows you to update the webhook URL associated with a processor token. This request triggers a WEBHOOK_UPDATE_ACKNOWLEDGED webhook to the newly specified webhook URL.

processor/token/webhook/update

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
processor_token
requiredstring
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor-<environment>-<identifier>
webhook
requiredstring
The new webhook URL to associate with the processor token. To remove a webhook from a processor token, set to null.
Select Language
1try {
2  const request: ProcessorTokenWebhookUpdateRequest = {
3    processor_token: processorToken,
4    webhook: webhook,
5  };
6  const response = await plaidClient.processorTokenWebhookUpdate(
7    request,
8  );
9} catch (error) {
10  // handle error
11}
processor/token/webhook/update

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "vYK11LNTfRoAMbj"
3}
Was this helpful?

/processor/stripe/bank_account_token/create

Create Stripe bank account token

Used to create a token suitable for sending to Stripe to enable Plaid-Stripe integrations. For a detailed guide on integrating Stripe, see Add Stripe to your app.
Note that the Stripe bank account token is a one-time use token. To store bank account information for later use, you can use a Stripe customer object and create an associated bank account from the token, or you can use a Stripe Custom account and create an associated external bank account from the token. This bank account information should work indefinitely, unless the user's bank account information changes or they revoke Plaid's permissions to access their account. Stripe bank account information cannot be modified once the bank account token has been created. If you ever need to change the bank account details used by Stripe for a specific customer, have the user go through Link again and create a new bank account token from the new access_token.
Bank account tokens can also be revoked, using /item/remove.

processor/stripe/bank_account_token/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
account_id
requiredstring
The account_id value obtained from the onSuccess callback in Link
Select group for content switcher
Select Language
1// Change sandbox to development to test with live users and change
2// to production when you're ready to go live!
3const {
4  Configuration,
5  PlaidApi,
6  PlaidEnvironments,
7  ProcessorStripeBankAccountTokenCreateRequest,
8} = require('plaid');
9const configuration = new Configuration({
10  basePath: PlaidEnvironments[process.env.PLAID_ENV],
11  baseOptions: {
12    headers: {
13      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
14      'PLAID-SECRET': process.env.PLAID_SECRET,
15      'Plaid-Version': '2020-09-14',
16    },
17  },
18});
19
20const plaidClient = new PlaidApi(configuration);
21
22try {
23  // Exchange the public_token from Plaid Link for an access token.
24  const tokenResponse = await plaidClient.itemPublicTokenExchange({
25    public_token: PUBLIC_TOKEN,
26  });
27  const accessToken = tokenResponse.data.access_token;
28
29  // Generate a bank account token
30  const request: ProcessorStripeBankAccountTokenCreateRequest = {
31    access_token: accessToken,
32    account_id: accountID,
33  };
34  const stripeTokenResponse = await plaidClient.processorStripeBankAccountTokenCreate(
35    request,
36  );
37  const bankAccountToken = stripeTokenResponse.data.stripe_bank_account_token;
38} catch (error) {
39  // handle error
40}
processor/stripe/bank_account_token/create

Response fields and example

stripe_bank_account_token
string
A token that can be sent to Stripe for use in making API calls to Plaid
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "stripe_bank_account_token": "btok_5oEetfLzPklE1fwJZ7SG",
3  "request_id": "xrQNYZ7Zoh6R7gV"
4}
Was this helpful?

Processor endpoints

Partner processor endpoints are used by Plaid partners to integrate with Plaid. Instead of using an access_token associated with a Plaid Item, these endpoints use a processor_token to identify a single financial account. These endpoints are used only by partners and not by developers who are using those partners' APIs. If you are a Plaid developer who would like to learn how to move money with one of our partners, see Move money with Auth.

Note that /signal/prepare isn't available as a processor endpoint because /signal/prepare adds Signal to an Item, which can only be done by the client who created the Item.

In this section
/processor/auth/getFetch Auth data
/processor/balance/getFetch Balance data
/processor/identity/getFetch Identity data
/processor/identity/matchRetrieve Identity match scores
/processor/signal/evaluateRetrieve Signal scores
/processor/signal/decision/reportReport whether you initiated an ACH transaction
/processor/signal/return/reportReport a return for an ACH transaction
/processor/transactions/syncGet transaction data or incremental transaction updates
/processor/transactions/getFetch transaction data
/processor/transactions/recurring/getFetch recurring transaction data
/processor/transactions/refreshRefresh transaction data

/processor/auth/get

Retrieve Auth data

The /processor/auth/get endpoint returns the bank account and bank identification number (such as the routing number, for US accounts), for a checking or savings account that''s associated with a given processor_token. The endpoint also returns high-level account data and balances when available.
Versioning note: API versions 2019-05-29 and earlier use a different schema for the numbers object returned by this endpoint. For details, see Plaid API versioning.

processor/auth/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
processor_token
requiredstring
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor-<environment>-<identifier>
Select group for content switcher
Select Language
1const request: ProcessorAuthGetRequest = {
2  processor_token: processorToken,
3};
4const response = plaidClient.processorAuthGet(request);
processor/auth/get

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
numbers
object
An object containing identifying numbers used for making electronic transfers to and from the account. The identifying number type (ACH, EFT, IBAN, or BACS) used will depend on the country of the account. An account may have more than one number type. If a particular identifying number type is not used by the account for which auth data has been requested, a null value will be returned.
ach
nullableobject
Identifying information for transferring money to or from a US account via ACH or wire transfer.
account_id
string
The Plaid account ID associated with the account numbers
account
string
The ACH account number for the account.
Note that when using OAuth with Chase Bank (ins_56), Chase will issue "tokenized" routing and account numbers, which are not the user's actual account and routing numbers. These tokenized account numbers (also known as TANs) should work identically to normal account and routing numbers. The digits returned in the mask field will continue to reflect the actual account number, rather than the tokenized account number; for this reason, when displaying account numbers to the user to help them identify their account in your UI, always use the mask rather than truncating the account number. If a user revokes their permissions to your app, the tokenized numbers will continue to work for ACH deposits, but not withdrawals.
routing
string
The ACH routing number for the account. If the institution is ins_56, this may be a tokenized routing number. For more information, see the description of the account field.
wire_routing
nullablestring
The wire transfer routing number for the account, if available
eft
nullableobject
Identifying information for transferring money to or from a Canadian bank account via EFT.
account_id
string
The Plaid account ID associated with the account numbers
account
string
The EFT account number for the account
institution
string
The EFT institution number for the account
branch
string
The EFT branch number for the account
international
nullableobject
Identifying information for transferring money to or from an international bank account via wire transfer.
account_id
string
The Plaid account ID associated with the account numbers
iban
string
The International Bank Account Number (IBAN) for the account
bic
string
The Bank Identifier Code (BIC) for the account
bacs
nullableobject
Identifying information for transferring money to or from a UK bank account via BACS.
account_id
string
The Plaid account ID associated with the account numbers
account
string
The BACS account number for the account
sort_code
string
The BACS sort code for the account
account
object
A single account at a financial institution.
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullablenumber
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullablenumber
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullablenumber
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullablestring
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
1{
2  "account": {
3    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
4    "balances": {
5      "available": 100,
6      "current": 110,
7      "iso_currency_code": "USD",
8      "limit": null,
9      "unofficial_currency_code": null
10    },
11    "mask": "0000",
12    "name": "Plaid Checking",
13    "official_name": "Plaid Gold Checking",
14    "subtype": "checking",
15    "type": "depository"
16  },
17  "numbers": {
18    "ach": {
19      "account": "9900009606",
20      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
21      "routing": "011401533",
22      "wire_routing": "021000021"
23    },
24    "eft": {
25      "account": "111122223333",
26      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
27      "institution": "021",
28      "branch": "01140"
29    },
30    "international": {
31      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
32      "bic": "NWBKGB21",
33      "iban": "GB29NWBK60161331926819"
34    },
35    "bacs": {
36      "account": "31926819",
37      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
38      "sort_code": "601613"
39    }
40  },
41  "request_id": "1zlMf"
42}
Was this helpful?

/processor/balance/get

Retrieve Balance data

The /processor/balance/get endpoint returns the real-time balance for each of an Item's accounts. While other endpoints may return a balance object, only /processor/balance/get forces the available and current balance fields to be refreshed rather than cached.

processor/balance/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
processor_token
requiredstring
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor-<environment>-<identifier>
options
object
An optional object to filter /processor/balance/get results.
min_last_updated_datetime
string
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the oldest acceptable balance when making a request to /accounts/balance/get.
If the balance that is pulled for ins_128026 (Capital One) is older than the given timestamp, an INVALID_REQUEST error with the code of LAST_UPDATED_DATETIME_OUT_OF_RANGE will be returned with the most recent timestamp for the requested account contained in the response.
This field is only used when the institution is ins_128026 (Capital One), in which case a value must be provided or an INVALID_REQUEST error with the code of INVALID_FIELD will be returned. For all other institutions, this field is ignored.

Format: date-time
Select group for content switcher
Select Language
1const request: ProcessorBalanceGetRequest = {
2  processor_token: processorToken,
3};
4const response = plaidClient.processorBalanceGet(request);
processor/balance/get

Response fields and example

account
object
A single account at a financial institution.
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullablenumber
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullablenumber
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullablenumber
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullablestring
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "account": {
3    "account_id": "QKKzevvp33HxPWpoqn6rI13BxW4awNSjnw4xv",
4    "balances": {
5      "available": 100,
6      "current": 110,
7      "limit": null,
8      "iso_currency_code": "USD",
9      "unofficial_currency_code": null
10    },
11    "mask": "0000",
12    "name": "Plaid Checking",
13    "official_name": "Plaid Gold Checking",
14    "subtype": "checking",
15    "type": "depository"
16  },
17  "request_id": "1zlMf"
18}
Was this helpful?

/processor/identity/get

Retrieve Identity data

The /processor/identity/get endpoint allows you to retrieve various account holder information on file with the financial institution, including names, emails, phone numbers, and addresses.

processor/identity/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
processor_token
requiredstring
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor-<environment>-<identifier>
Select group for content switcher
Select Language
1const request: ProcessorIdentityGetRequest = {
2  processor_token: processorToken,
3};
4const response = plaidClient.processorIdentityGet(request);
processor/identity/get

Response fields and example

account
object
A single account at a financial institution.
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullablenumber
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullablenumber
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullablenumber
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullablestring
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
owners
[object]
Data returned by the financial institution about the account owner or owners. Only returned by Identity or Assets endpoints. For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution. Multiple owners on a single account will be represented in the same owner object, not in multiple owner objects within the array. In API versions 2018-05-22 and earlier, the owners object is not returned, and instead identity information is returned in the top level identity object. For more details, see Plaid API versioning
names
[string]
A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders.
If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.
phone_numbers
[object]
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
string
The phone number.
primary
boolean
When true, identifies the phone number as the primary number on an account.
type
string
The type of phone number.

Possible values: home, work, office, mobile, mobile1, other
emails
[object]
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
string
The email address.
primary
boolean
When true, identifies the email address as the primary email on an account.
type
string
The type of email account as described by the financial institution.

Possible values: primary, secondary, other
addresses
[object]
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
object
Data about the components comprising an address.
city
nullablestring
The full city name
region
nullablestring
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
nullablestring
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code
primary
boolean
When true, identifies the address as the primary address on an account.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "account": {
3    "account_id": "XMGPJy4q1gsQoKd5z9R3tK8kJ9EWL8SdkgKMq",
4    "balances": {
5      "available": 100,
6      "current": 110,
7      "iso_currency_code": "USD",
8      "limit": null,
9      "unofficial_currency_code": null
10    },
11    "mask": "0000",
12    "name": "Plaid Checking",
13    "official_name": "Plaid Gold Standard 0% Interest Checking",
14    "owners": [
15      {
16        "addresses": [
17          {
18            "data": {
19              "city": "Malakoff",
20              "country": "US",
21              "postal_code": "14236",
22              "region": "NY",
23              "street": "2992 Cameron Road"
24            },
25            "primary": true
26          },
27          {
28            "data": {
29              "city": "San Matias",
30              "country": "US",
31              "postal_code": "93405-2255",
32              "region": "CA",
33              "street": "2493 Leisure Lane"
34            },
35            "primary": false
36          }
37        ],
38        "emails": [
39          {
40            "data": "accountholder0@example.com",
41            "primary": true,
42            "type": "primary"
43          },
44          {
45            "data": "accountholder1@example.com",
46            "primary": false,
47            "type": "secondary"
48          },
49          {
50            "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
51            "primary": false,
52            "type": "other"
53          }
54        ],
55        "names": [
56          "Alberta Bobbeth Charleson"
57        ],
58        "phone_numbers": [
59          {
60            "data": "1112223333",
61            "primary": false,
62            "type": "home"
63          },
64          {
65            "data": "1112224444",
66            "primary": false,
67            "type": "work"
68          },
69          {
70            "data": "1112225555",
71            "primary": false,
72            "type": "mobile1"
73          }
74        ]
75      }
76    ],
77    "subtype": "checking",
78    "type": "depository"
79  },
80  "request_id": "eOPkBl6t33veI2J"
81}
Was this helpful?

/processor/identity/match

Retrieve identity match score

The /processor/identity/match endpoint generates a match score, which indicates how well the provided identity data matches the identity information on file with the account holder's financial institution.
This request may take some time to complete if Identity was not specified as an initial product when creating the Item. This is because Plaid must communicate directly with the institution to retrieve the data.

processor/identity/match

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
processor_token
requiredstring
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor-<environment>-<identifier>
user
object
The user's legal name, phone number, email address and address used to perform fuzzy match. If Financial Account Matching is enabled in the Identity Verification product, leave this field empty to automatically match against PII collected from the Identity Verification checks.
legal_name
string
The user's full legal name.
phone_number
string
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis.
email_address
string
The user's email address.
address
object
Data about the components comprising an address.
city
string
The full city name
region
string
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
string
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
string
The ISO 3166-1 alpha-2 country code
Select Language
1const request: ProcessorIdentityMatchRequest = {
2    processor_token: processorToken,
3};
4const response = plaidClient.processorIdentityMatch(request);
processor/identity/match

Response fields and example

account
object
A single account at a financial institution.
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullablenumber
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullablenumber
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullablenumber
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullablestring
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
legal_name
nullableobject
Score found by matching name provided by the API with the name on the account at the financial institution. If the account contains multiple owners, the maximum match score is filled.
score
nullableinteger
Match score for name. 100 is a perfect score, 99-85 means a strong match, 84-70 is a partial match, any score less than 70 is a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the name is missing from either the API or financial institution, this is null.
is_first_name_or_last_name_match
nullableboolean
first or last name completely matched, likely a family member
is_nickname_match
nullableboolean
nickname matched, example Jennifer and Jenn.
is_business_name_detected
deprecatednullableboolean
Is true if the name on either of the names that was matched for the score contained strings indicative of a business name, such as "CORP", "LLC", "INC", or "LTD". A true result generally indicates the entity is a business. However, a false result does not mean the entity is not a business, as some businesses do not use these strings in the names used for their financial institution accounts.
phone_number
nullableobject
Score found by matching phone number provided by the API with the phone number on the account at the financial institution. 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled.
score
nullableinteger
Match score for normalized phone number. 100 is a perfect match, 99-70 is a partial match (matching the same phone number with extension against one without extension etc.), anything below 70 is considered a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the phone number is missing from either the API or financial institution, this is null.
email_address
nullableobject
Score found by matching email provided by the API with the email on the account at the financial institution. 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled.
score
nullableinteger
Match score for normalized email. 100 is a perfect match, 99-70 is a partial match (matching the same email with different '+' extensions), anything below 70 is considered a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the email is missing from either the API or financial institution, this is null.
address
nullableobject
Score found by matching address provided by the API with the address on the account at the financial institution. The score can range from 0 to 100 where 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled.
score
nullableinteger
Match score for address. 100 is a perfect match, 99-90 is a strong match, 89-80 is a partial match, anything below 80 is considered a weak match. Typically, the match threshold should be set to a score of 80 or higher. If the address is missing from either the API or financial institution, this is null.
is_postal_code_match
nullableboolean
postal code was provided for both and was a match
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "account": {
3    "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
4    "balances": {
5      "available": 100,
6      "current": 110,
7      "iso_currency_code": "USD",
8      "limit": null,
9      "unofficial_currency_code": null
10    },
11    "mask": "0000",
12    "name": "Plaid Checking",
13    "official_name": "Plaid Gold Standard 0% Interest Checking",
14    "legal_name": {
15      "score": 90,
16      "is_nickname_match": true,
17      "is_first_name_or_last_name_match": true,
18      "is_business_name_detected": false
19    },
20    "phone_number": {
21      "score": 100
22    },
23    "email_address": {
24      "score": 100
25    },
26    "address": {
27      "score": 100,
28      "is_postal_code_match": true
29    },
30    "subtype": "checking",
31    "type": "depository"
32  },
33  "request_id": "3nARps6TOYtbACO"
34}
Was this helpful?

/processor/signal/evaluate

Evaluate a planned ACH transaction

Use /processor/signal/evaluate to evaluate a planned ACH transaction as a processor to get a return risk assessment (such as a risk score and risk tier) and additional risk signals.
In order to obtain a valid score for an ACH transaction, Plaid must have an access token for the account, and the Item must be healthy (receiving product updates) or have recently been in a healthy state. If the transaction does not meet eligibility requirements, an error will be returned corresponding to the underlying cause. If /processor/signal/evaluate is called on the same transaction multiple times within a 24-hour period, cached results may be returned. For more information please refer to our error documentation on item errors and Link in Update Mode.
Note: This request may take some time to complete if Signal is being added to an existing Item. This is because Plaid must communicate directly with the institution when retrieving the data for the first time. To reduce this latency, you can call /signal/prepare on the Item before you need to request Signal data.

processor/signal/evaluate

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
processor_token
requiredstring
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor-<environment>-<identifier>
client_transaction_id
requiredstring
The unique ID that you would like to use to refer to this transaction. For your convenience mapping your internal data, you could use your internal ID/identifier for this transaction. The max length for this field is 36 characters.

Min length: 1
Max length: 36
amount
requirednumber
The transaction amount, in USD (e.g. 102.05)

Format: double
user_present
boolean
true if the end user is present while initiating the ACH transfer and the endpoint is being called; false otherwise (for example, when the ACH transfer is scheduled and the end user is not present, or you call this endpoint after the ACH transfer but before submitting the Nacha file for ACH processing).
client_user_id
string
A unique ID that identifies the end user in your system. This ID is used to correlate requests by a user with multiple Items. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.
is_recurring
boolean
true if the ACH transaction is a recurring transaction; false otherwise
default_payment_method
string
The default ACH or non-ACH payment method to complete the transaction. SAME_DAY_ACH: Same Day ACH by NACHA. The debit transaction is processed and settled on the same day NEXT_DAY_ACH: Next Day ACH settlement for debit transactions, offered by some payment processors STANDARD_ACH: standard ACH by NACHA REAL_TIME_PAYMENTS: real-time payments such as RTP and FedNow DEBIT_CARD: if the default payment is over debit card networks MULTIPLE_PAYMENT_METHODS: if there is no default debit rail or there are multiple payment methods Possible values: SAME_DAY_ACH, NEXT_DAY_ACH, STANDARD_ACH, REAL_TIME_PAYMENTS, DEBIT_CARD, MULTIPLE_PAYMENT_METHODS
user
object
Details about the end user initiating the transaction (i.e., the account holder).
name
object
The user's legal name
prefix
string
The user's name prefix (e.g. "Mr.")
given_name
string
The user's given name. If the user has a one-word name, it should be provided in this field.
middle_name
string
The user's middle name
family_name
string
The user's family name / surname
suffix
string
The user's name suffix (e.g. "II")
phone_number
string
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567"
email_address
string
The user's email address.
address
object
Data about the components comprising an address.
city
string
The full city name
region
string
The region or state Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
string
The postal code
country
string
The ISO 3166-1 alpha-2 country code
device
object
Details about the end user's device
ip_address
string
The IP address of the device that initiated the transaction
user_agent
string
The user agent of the device that initiated the transaction (e.g. "Mozilla/5.0")
Select Language
1const eval_request = {
2  processor_token: "processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175",
3  client_transaction_id: "txn12345",
4  amount: 123.45,
5  client_user_id: "user1234",
6  user: {
7    name: {
8      prefix: "Ms.",
9      given_name: "Jane",
10      middle_name: "Leah",
11      family_name: "Doe",
12      suffix: "Jr.",
13    },
14    phone_number: "+14152223333",
15    email_address: "jane.doe@example.com",
16    address: {
17      street: "2493 Leisure Lane",
18      city: "San Matias",
19      region: "CA",
20      postal_code: "93405-2255",
21      country: "US",
22    },
23  },
24  device: {
25    ip_address: "198.30.2.2",
26    user_agent:"Mozilla/5.0 (iPhone; CPU iPhone OS 13_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Mobile/15E148 Safari/604.1",
27  },
28  user_present: true,
29};
30
31try {
32  const eval_response = await plaidClient.processorSignalEvaluate(eval_request);
33  const core_attributes = eval_response.data.core_attributes;
34  const scores = eval_response.data.scores;
35} catch (error) {
36  // handle error
37}
processor/signal/evaluate

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
scores
object
Risk scoring details broken down by risk category.
customer_initiated_return_risk
object
The object contains a risk score and a risk tier that evaluate the transaction return risk of an unauthorized debit. Common return codes in this category include: "R05", "R07", "R10", "R11", "R29". These returns typically have a return time frame of up to 60 calendar days. During this period, the customer of financial institutions can dispute a transaction as unauthorized.
score
integer
A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood.

Minimum: 1
Maximum: 99
risk_tier
integer
A tier corresponding to the projected likelihood that the transaction, if initiated, will be subject to a return.
In the customer_initiated_return_risk object, there are five risk tiers corresponding to the scores: 1: Predicted customer-initiated return incidence rate between 0.00% - 0.02% 2: Predicted customer-initiated return incidence rate between 0.02% - 0.05% 3: Predicted customer-initiated return incidence rate between 0.05% - 0.1% 4: Predicted customer-initiated return incidence rate between 0.1% - 0.5% 5: Predicted customer-initiated return incidence rate greater than 0.5%

Minimum: 1
Maximum: 5
bank_initiated_return_risk
object
The object contains a risk score and a risk tier that evaluate the transaction return risk because an account is overdrawn or because an ineligible account is used. Common return codes in this category include: "R01", "R02", "R03", "R04", "R06", "R08", "R09", "R13", "R16", "R17", "R20", "R23". These returns have a turnaround time of 2 banking days.
score
integer
A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood.

Minimum: 1
Maximum: 99
risk_tier
integer
In the bank_initiated_return_risk object, there are eight risk tiers corresponding to the scores: 1: Predicted bank-initiated return incidence rate between 0.0% - 0.5% 2: Predicted bank-initiated return incidence rate between 0.5% - 1.5% 3: Predicted bank-initiated return incidence rate between 1.5% - 3% 4: Predicted bank-initiated return incidence rate between 3% - 5% 5: Predicted bank-initiated return incidence rate between 5% - 10% 6: Predicted bank-initiated return incidence rate between 10% - 15% 7: Predicted bank-initiated return incidence rate between 15% and 50% 8: Predicted bank-initiated return incidence rate greater than 50%

Minimum: 1
Maximum: 8
core_attributes
object
The core attributes object contains additional data that can be used to assess the ACH return risk. Examples of data include:
days_since_first_plaid_connection: The number of days since the first time the Item was connected to an application via Plaid plaid_connections_count_7d: The number of times the Item has been connected to applications via Plaid over the past 7 days plaid_connections_count_30d: The number of times the Item has been connected to applications via Plaid over the past 30 days total_plaid_connections_count: The number of times the Item has been connected to applications via Plaid is_savings_or_money_market_account: Indicates whether the ACH transaction funding account is a savings/money market account
For the full list and detailed documentation of core attributes available, or to request that core attributes not be returned, contact Sales or your Plaid account manager
warnings
[object]
If bank information was not available to be used in the Signal model, this array contains warnings describing why bank data is missing. If you want to receive an API error instead of Signal scores in the case of missing bank data, file a support ticket or contact your Plaid account manager.
warning_type
string
A broad categorization of the warning. Safe for programmatic use.
warning_code
string
The warning code identifies a specific kind of warning that pertains to the error causing bank data to be missing. Safe for programmatic use. For more details on warning codes, please refer to Plaid standard error codes documentation. In case you receive the ITEM_LOGIN_REQUIRED warning, we recommend re-authenticating your user by implementing Link's update mode. This will guide your user to fix their credentials, allowing Plaid to start fetching data again for future Signal requests.
warning_message
string
A developer-friendly representation of the warning type. This may change over time and is not safe for programmatic use.
1{
2  "scores": {
3    "customer_initiated_return_risk": {
4      "score": 9,
5      "risk_tier": 1
6    },
7    "bank_initiated_return_risk": {
8      "score": 72,
9      "risk_tier": 7
10    }
11  },
12  "core_attributes": {
13    "days_since_first_plaid_connection": 510,
14    "plaid_connections_count_7d": 6,
15    "plaid_connections_count_30d": 7,
16    "total_plaid_connections_count": 15,
17    "is_savings_or_money_market_account": false
18  },
19  "warnings": [],
20  "request_id": "mdqfuVxeoza6mhu"
21}
Was this helpful?

/processor/signal/decision/report

Report whether you initiated an ACH transaction

After calling /processor/signal/evaluate, call /processor/signal/decision/report to report whether the transaction was initiated. This endpoint will return an INVALID_FIELD error if called a second time with a different value for initiated.

processor/signal/decision/report

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
processor_token
requiredstring
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor-<environment>-<identifier>
client_transaction_id
requiredstring
Must be the same as the client_transaction_id supplied when calling /signal/evaluate

Min length: 1
Max length: 36
initiated
requiredboolean
true if the ACH transaction was initiated, false otherwise.
This field must be returned as a boolean. If formatted incorrectly, this will result in an INVALID_FIELD error.
days_funds_on_hold
integer
The actual number of days (hold time) since the ACH debit transaction that you wait before making funds available to your customers. The holding time could affect the ACH return rate.
For example, use 0 if you make funds available to your customers instantly or the same day following the debit transaction, or 1 if you make funds available the next day following the debit initialization.

Minimum: 0
decision_outcome
string
The payment decision from the risk assessment.
APPROVE: approve the transaction without requiring further actions from your customers. For example, use this field if you are placing a standard hold for all the approved transactions before making funds available to your customers. You should also use this field if you decide to accelerate the fund availability for your customers.
REVIEW: the transaction requires manual review
REJECT: reject the transaction
TAKE_OTHER_RISK_MEASURES: for example, placing a longer hold on funds than those approved transactions or introducing customer frictions such as step-up verification/authentication
NOT_EVALUATED: if only logging the Signal results without using them
Possible values: APPROVE, REVIEW, REJECT, TAKE_OTHER_RISK_MEASURES, NOT_EVALUATED

Possible values: APPROVE, REVIEW, REJECT, TAKE_OTHER_RISK_MEASURES, NOT_EVALUATED
payment_method
string
The payment method to complete the transaction after the risk assessment. It may be different from the default payment method.
SAME_DAY_ACH: Same Day ACH by NACHA. The debit transaction is processed and settled on the same day
NEXT_DAY_ACH: Next Day ACH settlement for debit transactions, offered by some payment processors
STANDARD_ACH: standard ACH by NACHA
REAL_TIME_PAYMENTS: real-time payments such as RTP and FedNow
DEBIT_CARD: if the default payment is over debit card networks
MULTIPLE_PAYMENT_METHODS: if there is no default debit rail or there are multiple payment methods
Possible values: SAME_DAY_ACH, NEXT_DAY_ACH, STANDARD_ACH, REAL_TIME_PAYMENTS, DEBIT_CARD, MULTIPLE_PAYMENT_METHODS

Possible values: SAME_DAY_ACH, NEXT_DAY_ACH, STANDARD_ACH, REAL_TIME_PAYMENTS, DEBIT_CARD, MULTIPLE_PAYMENT_METHODS
amount_instantly_available
number
The amount (in USD) made available to your customers instantly following the debit transaction. It could be a partial amount of the requested transaction (example: 102.05).

Format: double
Select Language
1const decision_report_request = {
2  processor_token: "processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175",
3  client_transaction_id: "txn12345",
4  initiated: true,
5  days_funds_on_hold: 3,
6};
7
8try {
9  const decision_report_response = await plaidClient.processorSignalDecisionReport(decision_report_request);
10  const decision_request_id = decision_report_response.data.request_id;
11} catch (error) {
12  // handle error
13}
processor/signal/decision/report

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "mdqfuVxeoza6mhu"
3}
Was this helpful?

/processor/signal/return/report

Report a return for an ACH transaction

Call the /processor/signal/return/report endpoint to report a returned transaction that was previously sent to the /processor/signal/evaluate endpoint. Your feedback will be used by the model to incorporate the latest risk trend in your portfolio.

processor/signal/return/report

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
processor_token
requiredstring
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor-<environment>-<identifier>
client_transaction_id
requiredstring
Must be the same as the client_transaction_id supplied when calling /processor/signal/evaluate

Min length: 1
Max length: 36
return_code
requiredstring
Must be a valid ACH return code (e.g. "R01")
If formatted incorrectly, this will result in an INVALID_FIELD error.
returned_at
string
Date and time when you receive the returns from your payment processors, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ).

Format: date-time
Select Language
1const return_report_request = {
2  processor_token: "processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175"
3  client_transaction_id: "txn12345",
4  return_code: "R01",
5};
6
7try {
8  const return_report_response = await plaidClient.processorSignalReturnReport(return_report_request);
9  const request_id = return_report_response.data.request_id;
10  console.log(request_id)
11} catch (error) {
12  // handle error
13}
processor/signal/return/report

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "mdqfuVxeoza6mhu"
3}
Was this helpful?

/processor/transactions/sync

Get incremental transaction updates on a processor token

This endpoint replaces /processor/transactions/get and its associated webhooks for most common use-cases.
The /processor/transactions/sync endpoint allows developers to subscribe to all transactions associated with a processor token and get updates synchronously in a stream-like manner, using a cursor to track which updates have already been seen. /processor/transactions/sync provides the same functionality as /processor/transactions/get and can be used instead of /processor/transactions/get to simplify the process of tracking transactions updates.
This endpoint provides user-authorized transaction data for credit, depository, and some loan-type accounts (only those with account subtype student; coverage may be limited). For transaction history from investments accounts, use /investments/transactions/get instead.
Returned transactions data is grouped into three types of update, indicating whether the transaction was added, removed, or modified since the last call to the API.
In the first call to /processor/transactions/sync for a processor token, the endpoint will return all historical transactions data associated with that processor token up until the time of the API call (as "adds"), which then generates a next_cursor for that processor token. In subsequent calls, send the next_cursor to receive only the changes that have occurred since the previous call.
Due to the potentially large number of transactions associated with a processor token, results are paginated. The has_more field specifies if additional calls are necessary to fetch all available transaction updates. Call /processor/transactions/sync with the new cursor, pulling all updates, until has_more is false.
When retrieving paginated updates, track both the next_cursor from the latest response and the original cursor from the first call in which has_more was true; if a call to /processor/transactions/sync fails when retrieving a paginated update, which can occur as a result of the TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION error, the entire pagination request loop must be restarted beginning with the cursor for the first page of the update, rather than retrying only the single request that failed.
Whenever new or updated transaction data becomes available, /processor/transactions/sync will provide these updates. Plaid typically checks for new data multiple times a day, but these checks may occur less frequently, such as once a day, depending on the institution. To force Plaid to check for new transactions, use the /processor/transactions/refresh endpoint.
Note that for newly created processor tokens, data may not be immediately available to /processor/transactions/sync. Plaid begins preparing transactions data when the corresponding Item is created, but the process can take anywhere from a few seconds to several minutes to complete, depending on the number of transactions available.
To receive Transactions webhooks for a processor token, set its webhook URL via the /processor/token/webhook/update endpoint.

processor/transactions/sync

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
processor_token
requiredstring
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor-<environment>-<identifier>
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
cursor
string
The cursor value represents the last update requested. Providing it will cause the response to only return changes after this update. If omitted, the entire history of updates will be returned, starting with the first-added transactions on the item. Note: The upper-bound length of this cursor is 256 characters of base64.
count
integer
The number of transaction updates to fetch.

Default: 100
Minimum: 1
Maximum: 500
Exclusive min: false
options
object
An optional object to be used with the request. If specified, options must not be null.
include_original_description
boolean
Include the raw unparsed transaction description from the financial institution. This field is disabled by default. If you need this information in addition to the parsed data provided, contact your Plaid Account Manager or submit a Support request.

Default: false
include_personal_finance_category
boolean
Include the personal_finance_category object in the response.
All implementations are encouraged to use set this field to true and to use the personal_finance_category instead of category for more meaningful and accurate categorization.
See the taxonomy csv file for a full list of personal finance categories.

Default: false
Select Language
1// Provide a cursor from your database if you've previously
2// received one for the Item. Leave null if this is your
3// first sync call for this Item. The first request will
4// return a cursor.
5let cursor = database.getLatestCursorOrNull(itemId);
6
7// New transaction updates since "cursor"
8let added: Array<Transaction> = [];
9let modified: Array<Transaction> = [];
10// Removed transaction ids
11let removed: Array<RemovedTransaction> = [];
12let hasMore = true;
13
14// Iterate through each page of new transaction updates for item
15while (hasMore) {
16  const request: ProcessorTransactionsSyncRequest = {
17    processor_token: processorToken,
18    cursor: cursor,
19  };
20  const response = await client.processorTransactionsSync(request);
21  const data = response.data;
22
23  // Add this page of results
24  added = added.concat(data.added);
25  modified = modified.concat(data.modified);
26  removed = removed.concat(data.removed);
27
28  hasMore = data.has_more;
29
30  // Update cursor to the next cursor
31  cursor = data.next_cursor;
32}
33
34// Persist cursor and updated data
35database.applyUpdates(itemId, added, modified, removed, cursor);
processor/transactions/sync

Response fields and example

added
[object]
Transactions that have been added to the Item since cursor ordered by ascending last modified time.
account_id
string
The ID of the account in which this transaction occurred.
amount
number
The settled value of the transaction, denominated in the transactions's currency, as stated in iso_currency_code or unofficial_currency_code. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the transaction. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the transaction. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
category
nullable[string]
A hierarchical array of the categories to which this transaction belongs. For a full list of categories, see /categories/get.
All Transactions implementations are recommended to use the new personal_finance_category instead of category. personal_finance_category provides more meaningful categorization and greater accuracy.
If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
category_id
nullablestring
The ID of the category to which this transaction belongs. For a full list of categories, see /categories/get.
All Transactions implementations are recommended to use the new personal_finance_category instead of category_id, as it provides greater accuracy and more meaningful categorization.
If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
check_number
nullablestring
The check number of the transaction. This field is only populated for check transactions.
date
string
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). To receive information about the date that a posted transaction was initiated, see the authorized_date field.

Format: date
location
object
A representation of where a transaction took place
address
nullablestring
The street address where the transaction occurred.
city
nullablestring
The city where the transaction occurred.
region
nullablestring
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.
postal_code
nullablestring
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code where the transaction occurred.
lat
nullablenumber
The latitude where the transaction occurred.

Format: double
lon
nullablenumber
The longitude where the transaction occurred.

Format: double
store_number
nullablestring
The merchant defined store number where the transaction occurred.
name
string
The merchant name or transaction description.
If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, this field will always appear. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
merchant_name
nullablestring
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.
original_description
nullablestring
The string returned by the financial institution to describe the transaction. For transactions returned by /transactions/sync or /transactions/get, this field is in beta and will be omitted unless the client is both enrolled in the closed beta program and has set options.include_original_description to true.
payment_meta
object
Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null.
If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, the payment_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
reference_number
nullablestring
The transaction reference number supplied by the financial institution.
ppd_id
nullablestring
The ACH PPD ID for the payer.
payee
nullablestring
For transfers, the party that is receiving the transaction.
by_order_of
nullablestring
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.
payer
nullablestring
For transfers, the party that is paying the transaction.
payment_method
nullablestring
The type of transfer, e.g. 'ACH'
payment_processor
nullablestring
The name of the payment processor
reason
nullablestring
The payer-supplied description of the transfer.
pending
boolean
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.
pending_transaction_id
nullablestring
The ID of a posted transaction's associated pending transaction, where applicable.
account_owner
nullablestring
The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts.
transaction_id
string
The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive.
transaction_type
deprecatedstring
Please use the payment_channel field, transaction_type will be deprecated in the future.
digital: transactions that took place online.
place: transactions that were made at a physical location.
special: transactions that relate to banks, e.g. fees or deposits.
unresolved: transactions that do not fit into the other three types.

Possible values: digital, place, special, unresolved
authorized_date
nullablestring
The date that the transaction was authorized. For posted transactions, the date field will indicate the posted date, but authorized_date will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized_date, when available, is generally preferable to use over the date field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an ISO 8601 format ( YYYY-MM-DD ).

Format: date
authorized_datetime
nullablestring
Date and time when a transaction was authorized in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For posted transactions, the datetime field will indicate the posted date, but authorized_datetime will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized_datetime, when available, is generally preferable to use over the datetime field for posted transactions, as it will generally represent the date the user actually made the transaction.
This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later.

Format: date-time
datetime
nullablestring
Date and time when a transaction was posted in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For the date that the transaction was initiated, rather than posted, see the authorized_datetime field.
This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later.

Format: date-time
payment_channel
string
The channel used to make a payment. online: transactions that took place online.
in store: transactions that were made at a physical location.
other: transactions that relate to banks, e.g. fees or deposits.
This field replaces the transaction_type field.

Possible values: online, in store, other
personal_finance_category
nullableobject
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases.
See the taxonomy csv file for a full list of personal finance categories.
primary
string
A high level category that communicates the broad category of the transaction.
detailed
string
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.
confidence_level
nullablestring
Note: This field is only available for /transactions/enrich endpoint currently. A description of how confident we are that the provided categories accurately describe the transaction intent.
VERY_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: Error
transaction_code
nullablestring
An identifier classifying the transaction type.
This field is only populated for European institutions. For institutions in the US and Canada, this field is set to null.
adjustment: Bank adjustment
atm: Cash deposit or withdrawal via an automated teller machine
bank charge: Charge or fee levied by the institution
bill payment: Payment of a bill
cash: Cash deposit or withdrawal
cashback: Cash withdrawal while making a debit card purchase
cheque: Document ordering the payment of money to another person or organization
direct debit: Automatic withdrawal of funds initiated by a third party at a regular interval
interest: Interest earned or incurred
purchase: Purchase made with a debit or credit card
standing order: Payment instructed by the account holder to a third party at a regular interval
transfer: Transfer of money between accounts

Possible values: adjustment, atm, bank charge, bill payment, cash, cashback, cheque, direct debit, interest, purchase, standing order, transfer, null
modified
[object]
Transactions that have been modified on the Item since cursor ordered by ascending last modified time.
account_id
string
The ID of the account in which this transaction occurred.
amount
number
The settled value of the transaction, denominated in the transactions's currency, as stated in iso_currency_code or unofficial_currency_code. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the transaction. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the transaction. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
category
nullable[string]
A hierarchical array of the categories to which this transaction belongs. For a full list of categories, see /categories/get.
All Transactions implementations are recommended to use the new personal_finance_category instead of category. personal_finance_category provides more meaningful categorization and greater accuracy.
If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
category_id
nullablestring
The ID of the category to which this transaction belongs. For a full list of categories, see /categories/get.
All Transactions implementations are recommended to use the new personal_finance_category instead of category_id, as it provides greater accuracy and more meaningful categorization.
If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
check_number
nullablestring
The check number of the transaction. This field is only populated for check transactions.
date
string
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). To receive information about the date that a posted transaction was initiated, see the authorized_date field.

Format: date
location
object
A representation of where a transaction took place
address
nullablestring
The street address where the transaction occurred.
city
nullablestring
The city where the transaction occurred.
region
nullablestring
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.
postal_code
nullablestring
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code where the transaction occurred.
lat
nullablenumber
The latitude where the transaction occurred.

Format: double
lon
nullablenumber
The longitude where the transaction occurred.

Format: double
store_number
nullablestring
The merchant defined store number where the transaction occurred.
name
string
The merchant name or transaction description.
If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, this field will always appear. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
merchant_name
nullablestring
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.
original_description
nullablestring
The string returned by the financial institution to describe the transaction. For transactions returned by /transactions/sync or /transactions/get, this field is in beta and will be omitted unless the client is both enrolled in the closed beta program and has set options.include_original_description to true.
payment_meta
object
Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null.
If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, the payment_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
reference_number
nullablestring
The transaction reference number supplied by the financial institution.
ppd_id
nullablestring
The ACH PPD ID for the payer.
payee
nullablestring
For transfers, the party that is receiving the transaction.
by_order_of
nullablestring
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.
payer
nullablestring
For transfers, the party that is paying the transaction.
payment_method
nullablestring
The type of transfer, e.g. 'ACH'
payment_processor
nullablestring
The name of the payment processor
reason
nullablestring
The payer-supplied description of the transfer.
pending
boolean
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.
pending_transaction_id
nullablestring
The ID of a posted transaction's associated pending transaction, where applicable.
account_owner
nullablestring
The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts.
transaction_id
string
The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive.
transaction_type
deprecatedstring
Please use the payment_channel field, transaction_type will be deprecated in the future.
digital: transactions that took place online.
place: transactions that were made at a physical location.
special: transactions that relate to banks, e.g. fees or deposits.
unresolved: transactions that do not fit into the other three types.

Possible values: digital, place, special, unresolved
authorized_date
nullablestring
The date that the transaction was authorized. For posted transactions, the date field will indicate the posted date, but authorized_date will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized_date, when available, is generally preferable to use over the date field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an ISO 8601 format ( YYYY-MM-DD ).

Format: date
authorized_datetime
nullablestring
Date and time when a transaction was authorized in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For posted transactions, the datetime field will indicate the posted date, but authorized_datetime will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized_datetime, when available, is generally preferable to use over the datetime field for posted transactions, as it will generally represent the date the user actually made the transaction.
This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later.

Format: date-time
datetime
nullablestring
Date and time when a transaction was posted in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For the date that the transaction was initiated, rather than posted, see the authorized_datetime field.
This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later.

Format: date-time
payment_channel
string
The channel used to make a payment. online: transactions that took place online.
in store: transactions that were made at a physical location.
other: transactions that relate to banks, e.g. fees or deposits.
This field replaces the transaction_type field.

Possible values: online, in store, other
personal_finance_category
nullableobject
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases.
See the taxonomy csv file for a full list of personal finance categories.
primary
string
A high level category that communicates the broad category of the transaction.
detailed
string
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.
confidence_level
nullablestring
Note: This field is only available for /transactions/enrich endpoint currently. A description of how confident we are that the provided categories accurately describe the transaction intent.
VERY_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: Error
transaction_code
nullablestring
An identifier classifying the transaction type.
This field is only populated for European institutions. For institutions in the US and Canada, this field is set to null.
adjustment: Bank adjustment
atm: Cash deposit or withdrawal via an automated teller machine
bank charge: Charge or fee levied by the institution
bill payment: Payment of a bill
cash: Cash deposit or withdrawal
cashback: Cash withdrawal while making a debit card purchase
cheque: Document ordering the payment of money to another person or organization
direct debit: Automatic withdrawal of funds initiated by a third party at a regular interval
interest: Interest earned or incurred
purchase: Purchase made with a debit or credit card
standing order: Payment instructed by the account holder to a third party at a regular interval
transfer: Transfer of money between accounts

Possible values: adjustment, atm, bank charge, bill payment, cash, cashback, cheque, direct debit, interest, purchase, standing order, transfer, null
removed
[object]
Transactions that have been removed from the Item since cursor ordered by ascending last modified time.
transaction_id
string
The ID of the removed transaction.
next_cursor
string
Cursor used for fetching any future updates after the latest update provided in this response. The cursor obtained after all pages have been pulled (indicated by has_more being false) will be valid for at least 1 year. This cursor should be persisted for later calls. If transactions are not yet available, this will be an empty string.
has_more
boolean
Represents if more than requested count of transaction updates exist. If true, the additional updates can be fetched by making an additional request with cursor set to next_cursor. If has_more is true, it’s important to pull all available pages, to make it less likely for underlying data changes to conflict with pagination.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "added": [
3    {
4      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
5      "amount": 2307.21,
6      "iso_currency_code": "USD",
7      "unofficial_currency_code": null,
8      "category": [
9        "Shops",
10        "Computers and Electronics"
11      ],
12      "category_id": "19013000",
13      "check_number": null,
14      "date": "2022-02-03",
15      "datetime": "2022-02-03T11:00:00Z",
16      "authorized_date": "2022-02-03",
17      "authorized_datetime": "2022-02-03T10:34:50Z",
18      "location": {
19        "address": "300 Post St",
20        "city": "San Francisco",
21        "region": "CA",
22        "postal_code": "94108",
23        "country": "US",
24        "lat": 40.740352,
25        "lon": -74.001761,
26        "store_number": "1235"
27      },
28      "name": "Apple Store",
29      "merchant_name": "Apple",
30      "payment_meta": {
31        "by_order_of": null,
32        "payee": null,
33        "payer": null,
34        "payment_method": null,
35        "payment_processor": null,
36        "ppd_id": null,
37        "reason": null,
38        "reference_number": null
39      },
40      "payment_channel": "in store",
41      "pending": false,
42      "personal_finance_category": {
43        "detailed": "GENERAL_MERCHANDISE_ELECTRONICS",
44        "primary": "GENERAL_MERCHANDISE"
45      },
46      "pending_transaction_id": null,
47      "account_owner": null,
48      "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
49      "transaction_code": null
50    }
51  ],
52  "modified": [
53    {
54      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
55      "amount": 98.05,
56      "iso_currency_code": "USD",
57      "unofficial_currency_code": null,
58      "category": [
59        "Service",
60        "Utilities",
61        "Electric"
62      ],
63      "category_id": "18068005",
64      "check_number": null,
65      "date": "2022-02-28",
66      "datetime": "2022-02-28T11:00:00Z",
67      "authorized_date": "2022-02-28",
68      "authorized_datetime": "2022-02-28T10:34:50Z",
69      "location": {
70        "address": null,
71        "city": null,
72        "region": null,
73        "postal_code": null,
74        "country": null,
75        "lat": null,
76        "lon": null,
77        "store_number": null
78      },
79      "name": "ConEd Bill Payment",
80      "merchant_name": "ConEd",
81      "payment_meta": {
82        "by_order_of": null,
83        "payee": null,
84        "payer": null,
85        "payment_method": null,
86        "payment_processor": null,
87        "ppd_id": null,
88        "reason": null,
89        "reference_number": null
90      },
91      "payment_channel": "online",
92      "pending": false,
93      "pending_transaction_id": null,
94      "personal_finance_category": {
95        "detailed": "RENT_AND_UTILITIES_GAS_AND_ELECTRICITY",
96        "primary": "RENT_AND_UTILITIES"
97      },
98      "account_owner": null,
99      "transaction_id": "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0",
100      "transaction_code": null
101    }
102  ],
103  "removed": [
104    {
105      "transaction_id": "CmdQTNgems8BT1B7ibkoUXVPyAeehT3Tmzk0l"
106    }
107  ],
108  "next_cursor": "tVUUL15lYQN5rBnfDIc1I8xudpGdIlw9nsgeXWvhOfkECvUeR663i3Dt1uf/94S8ASkitgLcIiOSqNwzzp+bh89kirazha5vuZHBb2ZA5NtCDkkV",
109  "has_more": false,
110  "request_id": "45QSn"
111}
Was this helpful?

/processor/transactions/get

Get transaction data

The /processor/transactions/get endpoint allows developers to receive user-authorized transaction data for credit, depository, and some loan-type accounts (only those with account subtype student; coverage may be limited). Transaction data is standardized across financial institutions, and in many cases transactions are linked to a clean name, entity type, location, and category. Similarly, account data is standardized and returned with a clean name, number, balance, and other meta information where available.
Transactions are returned in reverse-chronological order, and the sequence of transaction ordering is stable and will not shift. Transactions are not immutable and can also be removed altogether by the institution; a removed transaction will no longer appear in /processor/transactions/get. For more details, see Pending and posted transactions.
Due to the potentially large number of transactions associated with a processor token, results are paginated. Manipulate the count and offset parameters in conjunction with the total_transactions response body field to fetch all available transactions.
Data returned by /processor/transactions/get will be the data available for the processor token as of the most recent successful check for new transactions. Plaid typically checks for new data multiple times a day, but these checks may occur less frequently, such as once a day, depending on the institution. To force Plaid to check for new transactions, you can use the /processor/transactions/refresh endpoint.
Note that data may not be immediately available to /processor/transactions/get. Plaid will begin to prepare transactions data upon Item link, if Link was initialized with transactions, or upon the first call to /processor/transactions/get, if it wasn't. If no transaction history is ready when /processor/transactions/get is called, it will return a PRODUCT_NOT_READY error.
To receive Transactions webhooks for a processor token, set its webhook URL via the /processor/token/webhook/update endpoint.

processor/transactions/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
options
object
An optional object to be used with the request. If specified, options must not be null.
account_ids
[string]
A list of account_ids to retrieve for the Item
Note: An error will be returned if a provided account_id is not associated with the Item.
count
integer
The number of transactions to fetch.

Default: 100
Minimum: 1
Maximum: 500
Exclusive min: false
offset
integer
The number of transactions to skip. The default value is 0.

Default: 0
Minimum: 0
include_original_description
boolean
Include the raw unparsed transaction description from the financial institution. This field is disabled by default. If you need this information in addition to the parsed data provided, contact your Plaid Account Manager, or submit a Support request .

Default: false
include_personal_finance_category
boolean
Include the personal_finance_category object in the response.
All implementations are encouraged to set this field to true and use the personal_finance_category instead of category. Personal finance categories are the preferred categorization system for transactions, providing higher accuracy and more meaningful categories.
See the taxonomy csv file for a full list of personal finance categories.

Default: false
processor_token
requiredstring
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor-<environment>-<identifier>
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
start_date
requiredstring
The earliest date for which data should be returned. Dates should be formatted as YYYY-MM-DD.

Format: date
end_date
requiredstring
The latest date for which data should be returned. Dates should be formatted as YYYY-MM-DD.

Format: date
Select Language
1const request: ProcessorTransactionsGetRequest = {
2  processor_token: processorToken,
3  start_date: '2018-01-01',
4  end_date: '2020-02-01'
5};
6try {
7  const response = await client.processorTransactionsGet(request);
8  let transactions = response.data.transactions;
9  const total_transactions = response.data.total_transactions;
10  // Manipulate the offset parameter to paginate
11  // transactions and retrieve all available data
12  while (transactions.length < total_transactions) {
13    const paginatedRequest: ProcessorTransactionsGetRequest = {
14      processor_token: processorToken,
15      start_date: '2018-01-01',
16      end_date: '2020-02-01',
17      options: {
18        offset: transactions.length,
19      },
20    };
21    const paginatedResponse = await client.processorTransactionsGet(paginatedRequest);
22    transactions = transactions.concat(
23      paginatedResponse.data.transactions,
24    );
25  }
26} catch((err) => {
27  // handle error
28}
processor/transactions/get

Response fields and example

accounts
[object]
An array containing the accounts associated with the Item for which transactions are being returned. Each transaction can be mapped to its corresponding account via the account_id field.
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullablenumber
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullablenumber
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullablenumber
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullablestring
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
transactions
[object]
An array containing transactions from the account. Transactions are returned in reverse chronological order, with the most recent at the beginning of the array. The maximum number of transactions returned is determined by the count parameter.
account_id
string
The ID of the account in which this transaction occurred.
amount
number
The settled value of the transaction, denominated in the transactions's currency, as stated in iso_currency_code or unofficial_currency_code. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the transaction. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the transaction. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
category
nullable[string]
A hierarchical array of the categories to which this transaction belongs. For a full list of categories, see /categories/get.
All Transactions implementations are recommended to use the new personal_finance_category instead of category. personal_finance_category provides more meaningful categorization and greater accuracy.
If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
category_id
nullablestring
The ID of the category to which this transaction belongs. For a full list of categories, see /categories/get.
All Transactions implementations are recommended to use the new personal_finance_category instead of category_id, as it provides greater accuracy and more meaningful categorization.
If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
check_number
nullablestring
The check number of the transaction. This field is only populated for check transactions.
date
string
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). To receive information about the date that a posted transaction was initiated, see the authorized_date field.

Format: date
location
object
A representation of where a transaction took place
address
nullablestring
The street address where the transaction occurred.
city
nullablestring
The city where the transaction occurred.
region
nullablestring
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.
postal_code
nullablestring
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code where the transaction occurred.
lat
nullablenumber
The latitude where the transaction occurred.

Format: double
lon
nullablenumber
The longitude where the transaction occurred.

Format: double
store_number
nullablestring
The merchant defined store number where the transaction occurred.
name
string
The merchant name or transaction description.
If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, this field will always appear. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
merchant_name
nullablestring
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.
original_description
nullablestring
The string returned by the financial institution to describe the transaction. For transactions returned by /transactions/sync or /transactions/get, this field is in beta and will be omitted unless the client is both enrolled in the closed beta program and has set options.include_original_description to true.
payment_meta
object
Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null.
If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, the payment_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
reference_number
nullablestring
The transaction reference number supplied by the financial institution.
ppd_id
nullablestring
The ACH PPD ID for the payer.
payee
nullablestring
For transfers, the party that is receiving the transaction.
by_order_of
nullablestring
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.
payer
nullablestring
For transfers, the party that is paying the transaction.
payment_method
nullablestring
The type of transfer, e.g. 'ACH'
payment_processor
nullablestring
The name of the payment processor
reason
nullablestring
The payer-supplied description of the transfer.
pending
boolean
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.
pending_transaction_id
nullablestring
The ID of a posted transaction's associated pending transaction, where applicable.
account_owner
nullablestring
The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts.
transaction_id
string
The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive.
transaction_type
deprecatedstring
Please use the payment_channel field, transaction_type will be deprecated in the future.
digital: transactions that took place online.
place: transactions that were made at a physical location.
special: transactions that relate to banks, e.g. fees or deposits.
unresolved: transactions that do not fit into the other three types.

Possible values: digital, place, special, unresolved
authorized_date
nullablestring
The date that the transaction was authorized. For posted transactions, the date field will indicate the posted date, but authorized_date will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized_date, when available, is generally preferable to use over the date field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an ISO 8601 format ( YYYY-MM-DD ).

Format: date
authorized_datetime
nullablestring
Date and time when a transaction was authorized in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For posted transactions, the datetime field will indicate the posted date, but authorized_datetime will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized_datetime, when available, is generally preferable to use over the datetime field for posted transactions, as it will generally represent the date the user actually made the transaction.
This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later.

Format: date-time
datetime
nullablestring
Date and time when a transaction was posted in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For the date that the transaction was initiated, rather than posted, see the authorized_datetime field.
This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later.

Format: date-time
payment_channel
string
The channel used to make a payment. online: transactions that took place online.
in store: transactions that were made at a physical location.
other: transactions that relate to banks, e.g. fees or deposits.
This field replaces the transaction_type field.

Possible values: online, in store, other
personal_finance_category
nullableobject
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases.
See the taxonomy csv file for a full list of personal finance categories.
primary
string
A high level category that communicates the broad category of the transaction.
detailed
string
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.
confidence_level
nullablestring
Note: This field is only available for /transactions/enrich endpoint currently. A description of how confident we are that the provided categories accurately describe the transaction intent.
VERY_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: Error
transaction_code
nullablestring
An identifier classifying the transaction type.
This field is only populated for European institutions. For institutions in the US and Canada, this field is set to null.
adjustment: Bank adjustment
atm: Cash deposit or withdrawal via an automated teller machine
bank charge: Charge or fee levied by the institution
bill payment: Payment of a bill
cash: Cash deposit or withdrawal
cashback: Cash withdrawal while making a debit card purchase
cheque: Document ordering the payment of money to another person or organization
direct debit: Automatic withdrawal of funds initiated by a third party at a regular interval
interest: Interest earned or incurred
purchase: Purchase made with a debit or credit card
standing order: Payment instructed by the account holder to a third party at a regular interval
transfer: Transfer of money between accounts

Possible values: adjustment, atm, bank charge, bill payment, cash, cashback, cheque, direct debit, interest, purchase, standing order, transfer, null
total_transactions
integer
The total number of transactions available within the date range specified. If total_transactions is larger than the size of the transactions array, more transactions are available and can be fetched via manipulating the offset parameter.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "accounts": [
3    {
4      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
5      "balances": {
6        "available": 110,
7        "current": 110,
8        "iso_currency_code": "USD",
9        "limit": null,
10        "unofficial_currency_code": null
11      },
12      "mask": "0000",
13      "name": "Plaid Checking",
14      "official_name": "Plaid Gold Standard 0% Interest Checking",
15      "subtype": "checking",
16      "type": "depository"
17    }
18  ],
19  "transactions": [
20    {
21      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
22      "amount": 2307.21,
23      "iso_currency_code": "USD",
24      "unofficial_currency_code": null,
25      "category": [
26        "Shops",
27        "Computers and Electronics"
28      ],
29      "category_id": "19013000",
30      "check_number": null,
31      "date": "2017-01-29",
32      "datetime": "2017-01-27T11:00:00Z",
33      "authorized_date": "2017-01-27",
34      "authorized_datetime": "2017-01-27T10:34:50Z",
35      "location": {
36        "address": "300 Post St",
37        "city": "San Francisco",
38        "region": "CA",
39        "postal_code": "94108",
40        "country": "US",
41        "lat": 40.740352,
42        "lon": -74.001761,
43        "store_number": "1235"
44      },
45      "name": "Apple Store",
46      "merchant_name": "Apple",
47      "payment_meta": {
48        "by_order_of": null,
49        "payee": null,
50        "payer": null,
51        "payment_method": null,
52        "payment_processor": null,
53        "ppd_id": null,
54        "reason": null,
55        "reference_number": null
56      },
57      "payment_channel": "in store",
58      "pending": false,
59      "pending_transaction_id": null,
60      "personal_finance_category": {
61        "detailed": "GENERAL_MERCHANDISE_ELECTRONICS",
62        "primary": "GENERAL_MERCHANDISE"
63      },
64      "account_owner": null,
65      "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
66      "transaction_code": null,
67      "transaction_type": "place"
68    }
69  ],
70  "total_transactions": 1,
71  "request_id": "45QSn"
72}
Was this helpful?

/processor/transactions/recurring/get

Fetch recurring transaction streams

The /processor/transactions/recurring/get endpoint allows developers to receive a summary of the recurring outflow and inflow streams (expenses and deposits) from a user’s checking, savings or credit card accounts. Additionally, Plaid provides key insights about each recurring stream including the category, merchant, last amount, and more. Developers can use these insights to build tools and experiences that help their users better manage cash flow, monitor subscriptions, reduce spend, and stay on track with bill payments.
This endpoint is offered as an add-on to Transactions. To request access to this endpoint, submit a product access request or contact your Plaid account manager.
This endpoint can only be called on a processor token that has already been initialized with Transactions (either during Link, by specifying it in /link/token/create; or after Link, by calling /processor/transactions/get or /processor/transactions/sync). Once all historical transactions have been fetched, call /processor/transactions/recurring/get to receive the Recurring Transactions streams and subscribe to the RECURRING_TRANSACTIONS_UPDATE webhook. To know when historical transactions have been fetched, if you are using /processor/transactions/sync listen for the SYNC_UPDATES_AVAILABLE webhook and check that the historical_update_complete field in the payload is true. If using /processor/transactions/get, listen for the HISTORICAL_UPDATE webhook.
After the initial call, you can call /processor/transactions/recurring/get endpoint at any point in the future to retrieve the latest summary of recurring streams. Listen to the RECURRING_TRANSACTIONS_UPDATE webhook to be notified when new updates are available.
To receive Transactions webhooks for a processor token, set its webhook URL via the /processor/token/webhook/update endpoint.

processor/transactions/recurring/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
processor_token
requiredstring
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor-<environment>-<identifier>
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
options
object
An optional object to be used with the request. If specified, options must not be null.
include_personal_finance_category
boolean
Include the personal_finance_category object for each transaction stream in the response.
All implementations are encouraged to set this field to true and to use the personal_finance_category field instead of category. Personal finance categories are the preferred categorization system for transactions, providing higher accuracy and more meaningful categories.
See the taxonomy csv file for a full list of personal finance categories.

Default: false
account_ids
required[string]
A list of account_ids to retrieve for the Item
Note: An error will be returned if a provided account_id is not associated with the Item.
Select Language
1const request: ProcessorTransactionsGetRequest = {
2  processor_token: processorToken,
3  account_ids : accountIds,
4};
5try {
6  const response = await client.processorTransactionsRecurringGet(request);
7  let inflowStreams = response.data.inflowStreams;
8  let outflowStreams = response.data.outflowStreams;
9  }
10} catch((err) => {
11  // handle error
12}
processor/transactions/recurring/get

Response fields and example

inflow_streams
[object]
An array of depository transaction streams.
account_id
string
The ID of the account to which the stream belongs
stream_id
string
A unique id for the stream
category
[string]
A hierarchical array of the categories to which this transaction belongs. See Categories.
All implementations are encouraged to use the new personal_finance_category instead of category. personal_finance_category provides more meaningful categorization and greater accuracy.
category_id
string
The ID of the category to which this transaction belongs. See Categories.
All implementations are encouraged to use the new personal_finance_category instead of category. personal_finance_category provides more meaningful categorization and greater accuracy.
description
string
A description of the transaction stream.
merchant_name
nullablestring
The merchant associated with the transaction stream.
first_date
string
The posted date of the earliest transaction in the stream.

Format: date
last_date
string
The posted date of the latest transaction in the stream.

Format: date
frequency
string
Describes the frequency of the transaction stream.
WEEKLY: Assigned to a transaction stream that occurs approximately every week.
BIWEEKLY: Assigned to a transaction stream that occurs approximately every 2 weeks.
SEMI_MONTHLY: Assigned to a transaction stream that occurs approximately twice per month. This frequency is typically seen for inflow transaction streams.
MONTHLY: Assigned to a transaction stream that occurs approximately every month.
ANNUALLY: Assigned to a transaction stream that occurs approximately every year.
UNKNOWN: Assigned to a transaction stream that does not fit any of the pre-defined frequencies.

Possible values: UNKNOWN, WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY, ANNUALLY
transaction_ids
[string]
An array of Plaid transaction IDs belonging to the stream, sorted by posted date.
average_amount
object
Object with data pertaining to an amount on the transaction stream.
amount
number
Represents the numerical value of an amount.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the amount. Always null if unofficial_currency_code is non-null.
See the currency code schema for a full listing of supported iso_currency_codes.
unofficial_currency_code
nullablestring
The unofficial currency code of the amount. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
last_amount
object
Object with data pertaining to an amount on the transaction stream.
amount
number
Represents the numerical value of an amount.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the amount. Always null if unofficial_currency_code is non-null.
See the currency code schema for a full listing of supported iso_currency_codes.
unofficial_currency_code
nullablestring
The unofficial currency code of the amount. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
is_active
boolean
Indicates whether the transaction stream is still live.
status
string
The current status of the transaction stream.
MATURE: A MATURE recurring stream should have at least 3 transactions and happen on a regular cadence (For Annual recurring stream, we will mark it MATURE after 2 instances).
EARLY_DETECTION: When a recurring transaction first appears in the transaction history and before it fulfills the requirement of a mature stream, the status will be EARLY_DETECTION.
TOMBSTONED: A stream that was previously in the EARLY_DETECTION status will move to the TOMBSTONED status when no further transactions were found at the next expected date.
UNKNOWN: A stream is assigned an UNKNOWN status when none of the other statuses are applicable.

Possible values: UNKNOWN, MATURE, EARLY_DETECTION, TOMBSTONED
personal_finance_category
nullableobject
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases.
See the taxonomy csv file for a full list of personal finance categories.
primary
string
A high level category that communicates the broad category of the transaction.
detailed
string
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.
confidence_level
nullablestring
Note: This field is only available for /transactions/enrich endpoint currently. A description of how confident we are that the provided categories accurately describe the transaction intent.
VERY_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: Error
outflow_streams
[object]
An array of expense transaction streams.
account_id
string
The ID of the account to which the stream belongs
stream_id
string
A unique id for the stream
category
[string]
A hierarchical array of the categories to which this transaction belongs. See Categories.
All implementations are encouraged to use the new personal_finance_category instead of category. personal_finance_category provides more meaningful categorization and greater accuracy.
category_id
string
The ID of the category to which this transaction belongs. See Categories.
All implementations are encouraged to use the new personal_finance_category instead of category. personal_finance_category provides more meaningful categorization and greater accuracy.
description
string
A description of the transaction stream.
merchant_name
nullablestring
The merchant associated with the transaction stream.
first_date
string
The posted date of the earliest transaction in the stream.

Format: date
last_date
string
The posted date of the latest transaction in the stream.

Format: date
frequency
string
Describes the frequency of the transaction stream.
WEEKLY: Assigned to a transaction stream that occurs approximately every week.
BIWEEKLY: Assigned to a transaction stream that occurs approximately every 2 weeks.
SEMI_MONTHLY: Assigned to a transaction stream that occurs approximately twice per month. This frequency is typically seen for inflow transaction streams.
MONTHLY: Assigned to a transaction stream that occurs approximately every month.
ANNUALLY: Assigned to a transaction stream that occurs approximately every year.
UNKNOWN: Assigned to a transaction stream that does not fit any of the pre-defined frequencies.

Possible values: UNKNOWN, WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY, ANNUALLY
transaction_ids
[string]
An array of Plaid transaction IDs belonging to the stream, sorted by posted date.
average_amount
object
Object with data pertaining to an amount on the transaction stream.
amount
number
Represents the numerical value of an amount.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the amount. Always null if unofficial_currency_code is non-null.
See the currency code schema for a full listing of supported iso_currency_codes.
unofficial_currency_code
nullablestring
The unofficial currency code of the amount. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
last_amount
object
Object with data pertaining to an amount on the transaction stream.
amount
number
Represents the numerical value of an amount.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the amount. Always null if unofficial_currency_code is non-null.
See the currency code schema for a full listing of supported iso_currency_codes.
unofficial_currency_code
nullablestring
The unofficial currency code of the amount. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
is_active
boolean
Indicates whether the transaction stream is still live.
status
string
The current status of the transaction stream.
MATURE: A MATURE recurring stream should have at least 3 transactions and happen on a regular cadence (For Annual recurring stream, we will mark it MATURE after 2 instances).
EARLY_DETECTION: When a recurring transaction first appears in the transaction history and before it fulfills the requirement of a mature stream, the status will be EARLY_DETECTION.
TOMBSTONED: A stream that was previously in the EARLY_DETECTION status will move to the TOMBSTONED status when no further transactions were found at the next expected date.
UNKNOWN: A stream is assigned an UNKNOWN status when none of the other statuses are applicable.

Possible values: UNKNOWN, MATURE, EARLY_DETECTION, TOMBSTONED
personal_finance_category
nullableobject
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases.
See the taxonomy csv file for a full list of personal finance categories.
primary
string
A high level category that communicates the broad category of the transaction.
detailed
string
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.
confidence_level
nullablestring
Note: This field is only available for /transactions/enrich endpoint currently. A description of how confident we are that the provided categories accurately describe the transaction intent.
VERY_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: Error
updated_datetime
string
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time transaction streams for the given account were updated on

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "updated_datetime": "2022-05-01T00:00:00Z",
3  "inflow_streams": [
4    {
5      "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
6      "stream_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nc",
7      "category": [
8        "Transfer",
9        "Payroll"
10      ],
11      "category_id": "21009000",
12      "description": "Platypus Payroll",
13      "merchant_name": null,
14      "personal_finance_category": {
15        "detailed": "INCOME_WAGES",
16        "primary": "INCOME"
17      },
18      "first_date": "2022-02-28",
19      "last_date": "2022-04-30",
20      "frequency": "SEMI_MONTHLY",
21      "transaction_ids": [
22        "nkeaNrDGrhdo6c4qZWDA8ekuIPuJ4Avg5nKfw",
23        "EfC5ekksdy30KuNzad2tQupW8WIPwvjXGbGHL",
24        "ozfvj3FFgp6frbXKJGitsDzck5eWQH7zOJBYd",
25        "QvdDE8AqVWo3bkBZ7WvCd7LskxVix8Q74iMoK",
26        "uQozFPfMzibBouS9h9tz4CsyvFll17jKLdPAF"
27      ],
28      "average_amount": {
29        "amount": -800,
30        "iso_currency_code": "USD",
31        "unofficial_currency_code": null
32      },
33      "last_amount": {
34        "amount": -1000,
35        "iso_currency_code": "USD",
36        "unofficial_currency_code": null
37      },
38      "is_active": true,
39      "status": "MATURE"
40    }
41  ],
42  "outflow_streams": [
43    {
44      "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDff",
45      "stream_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nd",
46      "category": [
47        "Service",
48        "Utilities",
49        "Electric"
50      ],
51      "category_id": "18068005",
52      "description": "ConEd Bill Payment",
53      "merchant_name": "ConEd",
54      "personal_finance_category": {
55        "detailed": "RENT_AND_UTILITIES_GAS_AND_ELECTRICITY",
56        "primary": "RENT_AND_UTILITIES"
57      },
58      "first_date": "2022-02-04",
59      "last_date": "2022-05-02",
60      "frequency": "MONTHLY",
61      "transaction_ids": [
62        "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0",
63        "HPDnUVgI5Pa0YQSl0rxwYRwVXeLyJXTWDAvpR",
64        "jEPoSfF8xzMClE9Ohj1he91QnvYoSdwg7IT8L",
65        "CmdQTNgems8BT1B7ibkoUXVPyAeehT3Tmzk0l"
66      ],
67      "average_amount": {
68        "amount": 85,
69        "iso_currency_code": "USD",
70        "unofficial_currency_code": null
71      },
72      "last_amount": {
73        "amount": 100,
74        "iso_currency_code": "USD",
75        "unofficial_currency_code": null
76      },
77      "is_active": true,
78      "status": "MATURE"
79    },
80    {
81      "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDff",
82      "stream_id": "SrBNJZDuUMweodmPmSOeOImwsWt53ZXfJQAfC",
83      "category": [
84        "Shops",
85        "Warehouses and Wholesale Stores"
86      ],
87      "category_id": "19051000",
88      "description": "Costco Annual Membership",
89      "merchant_name": "Costco",
90      "personal_finance_category": {
91        "detailed": "GENERAL_MERCHANDISE_SUPERSTORES",
92        "primary": "GENERAL_MERCHANDISE"
93      },
94      "first_date": "2022-01-23",
95      "last_date": "2023-01-22",
96      "frequency": "ANNUALLY",
97      "transaction_ids": [
98        "yqEBJ72cS4jFwcpxJcDuQr94oAQ1R1lMC33D4",
99        "Kz5Hm3cZCgpn4tMEKUGAGD6kAcxMBsEZDSwJJ"
100      ],
101      "average_amount": {
102        "amount": 120,
103        "iso_currency_code": "USD",
104        "unofficial_currency_code": null
105      },
106      "last_amount": {
107        "amount": 120,
108        "iso_currency_code": "USD",
109        "unofficial_currency_code": null
110      },
111      "is_active": true,
112      "status": "MATURE"
113    }
114  ],
115  "request_id": "tbFyCEqkU775ZGG"
116}
Was this helpful?

/processor/transactions/refresh

Refresh transaction data

/processor/transactions/refresh is an optional endpoint for users of the Transactions product. It initiates an on-demand extraction to fetch the newest transactions for a processor token. This on-demand extraction takes place in addition to the periodic extractions that automatically occur multiple times a day for any Transactions-enabled processor token. If changes to transactions are discovered after calling /processor/transactions/refresh, Plaid will fire a webhook: for /transactions/sync users, SYNC_UPDATES_AVAILABLE will be fired if there are any transactions updated, added, or removed. For users of both /processor/transactions/sync and /processor/transactions/get, TRANSACTIONS_REMOVED will be fired if any removed transactions are detected, and DEFAULT_UPDATE will be fired if any new transactions are detected. New transactions can be fetched by calling /processor/transactions/get or /processor/transactions/sync. Note that the /processor/transactions/refresh endpoint is not supported for Capital One (ins_128026) and will result in a PRODUCT_NOT_SUPPORTED error if called on a processor token from that institution.
/processor/transactions/refresh is offered as an add-on to Transactions and has a separate fee model. To request access to this endpoint, submit a product access request or contact your Plaid account manager.

processor/transactions/refresh

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
processor_token
requiredstring
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: processor-<environment>-<identifier>
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
Select Language
1const request: ProcessorTransactionsRefreshRequest = {
2  processor_token: processorToken,
3};
4try {
5  await plaidClient.processorTransactionsRefresh(request);
6} catch (error) {
7  // handle error
8}
processor/transactions/refresh

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "1vwmF5TBQwiqfwP"
3}
Was this helpful?

auth partnerships treasury prime

Add Treasury Prime to your app

Use Treasury Prime with Plaid Auth to send and receive payments!

Partnership Treasury Prime logo

Overview

Treasury Prime and Plaid have partnered to offer our customers a seamless solution for sending payments to authenticated bank accounts. Rather than handling account and routing numbers directly, customers can use Plaid Link to enable end users to instantly authenticate their bank account information.

Create a new counterparty within the Treasury Prime API platform by sending the Plaid auth token. The relevant counterparty fields will be automatically populated when the token is exchanged.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Treasury Prime account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Treasury Prime processor_token, which allows you to quickly and securely verify a bank funding source via Treasury Prime's API without having to store any sensitive banking information. Utilizing Plaid + Treasury Prime enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Treasury Prime in order to use the Plaid + Treasury Prime integration. You'll also need to enable your Plaid account for the Treasury Prime integration.

First, you will need to work with the Treasury Prime team to sign up for a Treasury Prime account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Treasury Prime to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Treasury Prime processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Treasury Prime, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Treasury Prime processor_token. You'll send this token to Treasury Prime and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Treasury Prime processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'treasury_prime',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Treasury Prime Production credentials prior to initiating live payment transactions in the Treasury Prime API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

api postman

Plaid Postman Collection

Learn more about the Plaid Postman Collection, which allows you to send API requests without code

Introduction

Interested in experimenting with the Plaid API without having to write a full-stack application? Plaid offers a Postman Collection as a convenient tool for exploring Plaid API endpoints without writing code. The Postman Collection provides pre-formatted requests for almost all of Plaid's API endpoints that you can call from their desktop application, or a web browser. All you have to do is fill in your API keys and any arguments.

To get started using the Postman collection, you will need a Plaid account with access to the Sandbox environment, an account at Postman.com, and (optionally) the Postman desktop application. Once you have all the prerequisites, visit our GitHub page and click the "Run in Postman" button to load up the Plaid collection of endpoints.

Plaid Postman view

liabilities

Introduction to Liabilities

Access data for student loans, mortgages, and credit cards using the Liabilities product.

Explore API

Overview

Plaid's Liabilities product allows you to access information about a user's debts. A common application is personal financial management tools to help customers manage or refinance debt.

Liabilities data

With Liabilities, you can view account information for credit cards, PayPal credit accounts, student loans, and mortgages in the US. Available information includes balance, next payment date and amount, loan terms such as duration and interest rate, and originator information such as the origination date and initial loan amount. Liabilities data is refreshed approximately once per day, and the latest data can be accessed by calling /liabilities/get.

Note that liabilities data does not contain detailed transaction history for credit card accounts. For credit card account transactions, use the Transactions product.

1"credit": [
2  {
3    "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
4    "aprs": [
5      {
6        "apr_percentage": 15.24,
7        "apr_type": "balance_transfer_apr",
8        "balance_subject_to_apr": 1562.32,
9        "interest_charge_amount": 130.22
10      },
11      {
12        "apr_percentage": 27.95,
13        "apr_type": "cash_apr",
14        "balance_subject_to_apr": 56.22,
15        "interest_charge_amount": 14.81
16      },
17      {
18        "apr_percentage": 12.5,
19        "apr_type": "purchase_apr",
20        "balance_subject_to_apr": 157.01,
21        "interest_charge_amount": 25.66
22      },
23      {
24        "apr_percentage": 0,
25        "apr_type": "special",
26        "balance_subject_to_apr": 1000,
27        "interest_charge_amount": 0
28      }
29    ],
30    "is_overdue": false,
31    "last_payment_amount": 168.25,
32    "last_payment_date": "2019-05-22",
33    "last_statement_issue_date": "2019-05-28",
34    "last_statement_balance": 1708.77,
35    "minimum_payment_amount": 20,
36    "next_payment_due_date": "2020-05-28"
37  }
38]
1"student": [
2  {
3    "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
4    "account_number": "4277075694",
5    "disbursement_dates": [
6      "2002-08-28"
7    ],
8    "expected_payoff_date": "2032-07-28",
9    "guarantor": "DEPT OF ED",
10    "interest_rate_percentage": 5.25,
11    "is_overdue": false,
12    "last_payment_amount": 138.05,
13    "last_payment_date": "2019-04-22",
14    "last_statement_issue_date": "2019-04-28",
15    "loan_name": "Consolidation",
16    "loan_status": {
17      "end_date": "2032-07-28",
18      "type": "repayment"
19    },
20    "minimum_payment_amount": 25,
21    "next_payment_due_date": "2019-05-28",
22    "origination_date": "2002-08-28",
23    "origination_principal_amount": 25000,
24    "outstanding_interest_amount": 6227.36,
25    "payment_reference_number": "4277075694",
26    "pslf_status": {
27      "estimated_eligibility_date": "2021-01-01",
28      "payments_made": 200,
29      "payments_remaining": 160
30    },
31    "repayment_plan": {
32      "description": "Standard Repayment",
33      "type": "standard"
34    },
35    "sequence_number": "1",
36    "servicer_address": {
37      "city": "San Matias",
38      "country": "US",
39      "postal_code": "99415",
40      "region": "CA",
41      "street": "123 Relaxation Road"
42    },
43    "ytd_interest_paid": 280.55,
44    "ytd_principal_paid": 271.65
45  }
46]
1"mortgage": [
2  {
3    "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
4    "account_number": "3120194154",
5    "current_late_fee": 25.0,
6    "escrow_balance": 3141.54,
7    "has_pmi": true,
8    "has_prepayment_penalty": true,
9    "interest_rate": {
10      "percentage": 3.99,
11      "type": "fixed",
12    },
13    "last_payment_amount": 3141.54,
14    "last_payment_date": "2019-08-01",
15    "loan_term": "30 year",
16    "loan_type_description": "conventional",
17    "maturity_date": "2045-07-31",
18    "next_monthly_payment": 3141.54,
19    "next_payment_due_date": "2019-11-15",
20    "origination_date": "2015-08-01",
21    "origination_principal_amount": 425000,
22    "past_due_amount": 2304,
23    "property_address": {
24      "city": "Malakoff",
25      "country": "US",
26      "postal_code": "14236",
27      "region": "NY",
28      "street": "2992 Cameron Road",
29    }
30    "ytd_interest_paid": 12300.4,
31    "ytd_principal_paid": 12340.5
32  }
33]

Payment history

The information returned by a /liabilities/get request contains recent payment information, such as the date and amount of the most recent payment. To view further payment history, you can use Plaid's Transactions product.

Liabilities webhooks

Plaid checks for updated Liabilities data approximately once per day and uses webhooks to inform you of any changes so you can keep your app up to date. For more detail on how to listen and respond to these webhooks, see Liabilities webhooks.

Testing Liabilities

Liabilities can be tested in Sandbox or Development without any additional permissions.

Plaid also provides a GitHub repo with test data for testing student loan accounts in Sandbox. For more information on configuring custom Sandbox data, see Configuring the custom user account.

Next steps

To get started building with Liabilities, see Add Liabilities to your App.

If you're ready to launch to Production, see the Launch checklist.

link maintain legacy integration

Maintaining a public-key based integration

Details and guidance on maintaining a legacy public_key based Link integration for older Plaid API versions.

Overview

In July 2020, Plaid introduced the link_token, which replaces the static public_key. While integrations using the public_key are still supported, it is recommended that you upgrade your integration to use a link_token instead, as future Plaid development and features will be based on the link_token infrastructure. To start upgrading, see the Link token migration guide.

Plaid Link for Web

This section provides instructions for maintaining Plaid integrations using the deprecated public_key parameter. These instructions cannot be used for new integrations or for adding OAuth support to existing integrations. For up-to-date content on this topic, see the Link Web SDK instead. For instructions on updating an existing legacy integration, see the Link token migration guide.

Installation

Include the Plaid Link initialize script on each page of your site. It should always be loaded directly from https://cdn.plaid.com, rather than included in a bundle or hosted yourself.

1<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>

Create

Plaid.create accepts one argument, a configuration Object, and returns an Object with two functions, open and exit. Calling open will display the Consent Pane view, and calling exit will close Link. Note: Control whether or not your Link integration uses the Account Select view from the Dashboard.

create_legacy
clientName
string
Displayed once a user has successfully linked their Item.
env
string
The Plaid API environment on which to create user accounts. Possible values are development, sandbox, respectively. For Production use, use production.
key
string
The public_key associated with your account; available from the Dashboard.
product
string
A list of Plaid products you wish to use. Valid products are: transactions, auth, identity, assets, investments, liabilities, and payment_initiation. Example: ['auth', 'transactions']. balance is not a valid value, the Balance product does not require explicit initialization and will automatically be initialized when any other product is initialized. Only institutions that support all requested products will be shown in Link.
In Production, you will be billed for each product that you specify when initializing Link. Note that a product cannot be removed from an Item once the Item has been initialized with that product. To stop billing on an Item for subscription-based products, such as Liabilities, Investments, and Transactions, remove the Item via /item/remove.
onSuccess
callback
A function that is called when a user successfully links an Item. The function should expect two arguments, the public_token and a metadata object. See onSuccess.
onExit
callback
A function that is called when a user has specifically exited the Link flow or if Link failed to initialize. The function should expect two arguments, a nullable error object and a metadata object. See onExit.
onEvent
callback
A function that is called when a user reaches certain points in the Link flow. The function should expect two arguments, an eventName string and a metadata object.
onLoad
callback
A function that is called when the Link module has finished loading. Calls to plaidLinkHandler.open() prior to the onLoad callback will be delayed until the module is fully loaded.
language
string
Specify a Plaid-supported language to localize Link. English will be used by default. Supported languages:
  • English ('en')
  • French ('fr')
  • Spanish ('es')
  • Dutch ('nl')
When using a Link customization, language must be set to match the language used in the customization.
countryCodes
string
Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard. Note that if you initialize with a European country code, your users will see the European consent panel during the Link flow. Supported country codes are: US, CA, ES, FR, GB, IE, NL. If not specified, will default to ['US']. If Link is launched with multiple countryCodes, only products that you are enabled for in all countries will be used by Link.
If a Link customization is being used, the countries configured here should match those in the customization.
To use the Auth features Instant Match, Automated Micro-deposits, or Same-day Micro-deposits, countryCodes must be set to ['US'].
accountSubtypes
object
By default, Link will only display account types that are compatible with all products supplied in the product parameter. You can further limit the accounts shown in Link by using accountSubtypes to specify the account subtypes to be shown in Link. Only the specified subtypes will be shown. To indicate that all subtypes should be shown, use the value "all". If the accountSubtypes filter is used, any account type for which a filter is not specified will be entirely omitted from Link.
Example value:
{
"depository": ["checking", "savings"],
"credit": ["all"]
}
For a full list of valid types and subtypes, see the Account schema.
For institutions using OAuth, the filter will not affect the list of institutions shown by the bank in the OAuth window.
<accountType>: [accountSubtype]
string
An object of accountTypes composed of an array of accountSubtypes to filter.
webhook
string
Specify a webhook to associate with an Item. Plaid fires a webhook when the Item requires updated credentials, when new data is available, or when Auth numbers have been successfully verified.
token
string
Specify a public_token to launch Link in update mode for a particular Item. This will cause Link to open directly to the authentication step for that Item's institution. Use the /item/public_token/create endpoint to generate a public_token for an Item.
linkCustomizationName
string
Specify the name of a Link customization created in the Dashboard. The default customization is used if none is provided. When using a Link customization, the language in the customization must match the language configured via the language parameter.
oauthNonce
string
An oauthNonce is required to support OAuth authentication flows when launching or re-launching Link on a mobile device and using one or more European country codes. The nonce must be at least 16 characters long.
oauthRedirectUri
string
An oauthRedirectUri is required to support OAuth authentication flows when launching Link on a mobile device. Note that any redirect URI must also be added to the Allowed redirect URIs list in the developer dashboard.
oauthStateId
string
An oauthStateId is required to support OAuth authentication flows when re-launching Link on a mobile device.
paymentToken
string
A paymentToken must be specified if you are using the Payment Initiation (UK and Europe) product. This will cause Link to open directly to the Payment Initiation flow. Use the /payment_initiation/payment/token/create endpoint to generate a payment_token.
userLegalName
string
The end user's legal name
userPhoneNumber
string
The end user's phone number
userEmailAddress
string
The end user's email address
1const handler = Plaid.create({
2  clientName: 'Plaid Quickstart',
3  env: 'sandbox',
4  key: 'PUBLIC_KEY',
5  product: ['transactions'],
6  onSuccess: (public_token, metadata) => {},
7  onLoad: () => {},
8  onExit: (err, metadata) => {},
9  onEvent: (eventName, metadata) => {},
10  countryCodes: ['US'],
11  webhook: 'https://requestb.in',
12  linkCustomizationName: '',
13  language: 'en',
14  oauthNonce: null,
15  oauthRedirectUri: null,
16  oauthStateId: null,
17  token: null,
18  paymentToken: null,
19});

onSuccess

The onSuccess callback is called when a user successfully links an Item. It takes two arguments: the public_token and a metadata object.

onSuccess
public_token
string
Displayed once a user has successfully linked their Item.
metadata
object
Displayed once a user has successfully linked their Item.
institution
nullableobject
An institution object. If the Item was created via Same-Day micro-deposit verification, will be null.
name
string
The full institution name, such as 'Wells Fargo'
institution_id
string
The Plaid institution identifier
accounts
object
A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, accounts will only include selected accounts.
id
string
The Plaid account_id
name
string
The official account name
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts. It may also not match the mask that the bank displays to the user.
type
string
The account type. See the Account schema for a full list of possible values
subtype
string
The account subtype. See the Account schema for a full list of possible values
verification_status
nullablestring
Indicates an Item's micro-deposit-based verification status. Possible values are:
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the two amounts.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.
null: micro-deposit-based verification is not being used for the Item.
class_type
nullablestring
If micro-deposit verification is being used, indicates whether the account being verified is a business or personal account.
account
deprecatednullableobject
Deprecated. Use accounts instead.
link_session_id
string
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
transfer_status
nullablestring
The status of a transfer. Returned only when Transfer UI is implemented.
  • COMPLETE – The transfer was completed.
  • INCOMPLETE – The transfer could not be completed. For help, see Troubleshooting transfers.


Possible values: COMPLETE, INCOMPLETE
1const handler = Plaid.create({
2  ...,
3  onSuccess: (public_token, metadata) => {
4    fetch('//yourserver.com/exchange_public_token', {
5      method: 'POST',
6      body: {
7        public_token: public_token,
8        accounts: metadata.accounts,
9        institution: metadata.institution,
10        link_session_id: metadata.link_session_id,
11      },
12    });
13  }
14});
1{
2  institution: {
3    name: 'Wells Fargo',
4    institution_id: 'ins_4'
5  },
6  accounts: [
7    {
8      id: 'ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy',
9      name: 'Plaid Checking',
10      mask: '0000',
11      type: 'depository',
12      subtype: 'checking',
13      verification_status: ''
14    },
15    {
16      id: '9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4',
17      name: 'Plaid Saving',
18      mask: '1111',
19      type: 'depository',
20      subtype: 'savings'
21    }
22    ...
23  ],
24  link_session_id: '79e772be-547d-4c9c-8b76-4ac4ed4c441a'
25}

onExit

The onExit callback is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. It takes two arguments, a nullable error object and a metadata object. The metadata parameter is always present, though some values may be null.

onExit
error
nullableobject
A nullable object that contains the error type, code, and message of the error that was last encountered by the user. If no error was encountered, error will be null.
error_type
String
A broad categorization of the error.
error_code
String
The particular error code. Each error_type has a specific set of error_codes.
error_message
String
A developer-friendly representation of the error code.
display_message
nullableString
A user-friendly representation of the error code. null if the error is not related to user action. This may change over time and is not safe for programmatic use.
metadata
object
Displayed once a user has successfully linked their Item.
institution
nullableobject
An institution object. If the Item was created via Same-Day micro-deposit verification, will be null.
name
string
The full institution name, such as Wells Fargo
institution_id
string
The Plaid institution identifier
status
string
The point at which the user exited the Link flow. One of the following values.
requires_questions
User prompted to answer security questions
requires_selections
User prompted to answer multiple choice question(s)
requires_code
User prompted to provide a one-time passcode
choose_device
User prompted to select a device on which to receive a one-time passcode
requires_credentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution
requires_account_selection
User prompted to select one or more financial accounts to share
requires_oauth
User prompted to enter an OAuth flow
institution_not_found
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
link_session_id
string
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
request_id
string
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation.
1const handler = Plaid.create({
2  ...,
3  onExit: (error, metadata) => {
4    // Save data from the onExit handler
5    supportHandler.report({
6      error: error,
7      institution: metadata.institution,
8      link_session_id: metadata.link_session_id,
9      plaid_request_id: metadata.request_id,
10      status: metadata.status,
11    });
12  },
13});
1{
2  error_type: 'ITEM_ERROR',
3  error_code: 'INVALID_CREDENTIALS',
4  error_message: 'the credentials were not correct',
5  display_message: 'The credentials were not correct.',
6}
1{
2  institution: {
3    name: 'Wells Fargo',
4    institution_id: 'ins_4'
5  },
6  status: 'requires_credentials',
7  link_session_id: '36e201e0-2280-46f0-a6ee-6d417b450438',
8  request_id: '8C7jNbDScC24THu'
9}

onEvent

The onEvent callback is called at certain points in the Link flow. It takes two arguments, an eventName string and a metadata object.
The metadata parameter is always present, though some values may be null. Note that new eventNames, metadata keys, or view names may be added without notice.
The onEvent callback is not guaranteed to fire exactly at the time of a user action in Link. In general, the OPEN event will fire in real time; subsequent events will fire at the end of the Link flow, along with the onSuccess or onExit callback. If you need to determine the exact time when an event happened, use the timestamp in the metadata.
The following callback events are stable, which means that they will not be deprecated or changed: OPEN, EXIT, HANDOFF, SELECT_INSTITUTION, ERROR, BANK_INCOME_INSIGHTS_COMPLETED, IDENTITY_VERIFICATION_PASS_SESSION, IDENTITY_VERIFICATION_FAIL_SESSION. The remaining callback events are informational and subject to change.

onEvent
eventName
string
A string representing the event that has just occurred in the Link flow.
BANK_INCOME_INSIGHTS_COMPLETED
The user has completed the Assets and Bank Income Insights flow.
CLOSE_OAUTH
The user closed the third-party website or mobile app without completing the OAuth flow.
ERROR
A recoverable error occurred in the Link flow, see the error_code metadata.
EXIT
The user has exited without completing the Link flow and the onExit callback is fired.
FAIL_OAUTH
The user encountered an error while completing the third-party's OAuth login flow.
HANDOFF
The user has exited Link after successfully linking an Item.
IDENTITY_VERIFICATION_START_STEP
The user has started a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_PASS_STEP
The user has passed a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_FAIL_STEP
The user has failed a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_PENDING_REVIEW_STEP
The user has reached the pending review state.
IDENTITY_VERIFICATION_CREATE_SESSION
The user has started a new Identity Verification session.
IDENTITY_VERIFICATION_RESUME_SESSION
The user has resumed an existing Identity Verification session.
IDENTITY_VERIFICATION_PASS_SESSION
The user has successfully completed their Identity Verification session.
IDENTITY_VERIFICATION_FAIL_SESSION
The user has failed their Identity Verification session.
IDENTITY_VERIFICATION_PENDING_REVIEW_SESSION
The user has completed their Identity Verification session, which is now in a pending review state.
IDENTITY_VERIFICATION_OPEN_UI
The user has opened the UI of their Identity Verification session.
IDENTITY_VERIFICATION_RESUME_UI
The user has resumed the UI of their Identity Verification session.
IDENTITY_VERIFICATION_CLOSE_UI
The user has closed the UI of their Identity Verification session.
MATCHED_SELECT_INSTITUTION
The user selected an institution that was presented as a matched institution. This event can be emitted either during the Returning User Experience flow or if the institution's routing_number was provided when calling /link/token/create. To distinguish between the two scenarios, see metadata.match_reason.
MATCHED_SELECT_VERIFY_METHOD
The user selected a verification method for a matched institution. This event is emitted during the Returning User Experience flow.
OPEN
The user has opened Link.
OPEN_MY_PLAID
The user has opened my.plaid.com. This event is only sent when Link is initialized with Assets as a product
OPEN_OAUTH
The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.
SEARCH_INSTITUTION
The user has searched for an institution.
SELECT_AUTH_TYPE
The user has chosen whether to Link instantly or manually (i.e., with micro-deposits). This event emits the selection metadata to indicate the user's selection.
SELECT_BRAND
The user selected a brand, e.g. Bank of America. The SELECT_BRAND event is only emitted for large financial institutions with multiple online banking portals.
SELECT_DEGRADED_INSTITUTION
The user selected an institution with a DEGRADED health status and was shown a corresponding message.
SELECT_DOWN_INSTITUTION
The user selected an institution with a DOWN health status and was shown a corresponding message.
SELECT_INSTITUTION
The user selected an institution.
SUBMIT_ACCOUNT_NUMBER
The user has submitted an account number. This event emits the account_number_mask metadata to indicate the mask of the account number the user provided.
SUBMIT_CREDENTIALS
The user has submitted credentials.
SUBMIT_DOCUMENTS
The user is being prompted to submit documents for an Income verification flow.
SUBMIT_DOCUMENTS_ERROR
The user encountered an error when submitting documents for an Income verification flow.
SUBMIT_DOCUMENTS_SUCCESS
The user has successfully submitted documents for an Income verification flow.
SUBMIT_MFA
The user has submitted MFA.
SUBMIT_ROUTING_NUMBER
The user has submitted routing number. This event emits the routing_number metadata to indicate user's routing number.
TRANSITION_VIEW
The TRANSITION_VIEW event indicates that the user has moved from one view to the next.
VIEW_DATA_TYPES
The user has viewed data types on the data transparency consent pane.
metadata
object
An object containing information about the event.
account_number_mask
nullablestring
The account number mask extracted from the user-provided account number. If the user-inputted account number is four digits long, account_number_mask is empty. Emitted by SUBMIT_ACCOUNT_NUMBER.
error_type
nullablestring
The error type that the user encountered. Emitted by: ERROR, EXIT.
error_code
nullablestring
The error code that the user encountered. Emitted by ERROR, EXIT.
error_message
nullablestring
The error message that the user encountered. Emitted by: ERROR, EXIT.
exit_status
nullablestring
The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT
institution_id
nullablestring
The ID of the selected institution. Emitted by: all events.
institution_name
nullablestring
The name of the selected institution. Emitted by: all events.
institution_search_query
nullablestring
The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.
is_update_mode
nullablestring
Indicates if the current Link session is an update mode session. Emitted by: OPEN.
match_reason
nullablestring
The reason this institution was matched, which will be either returning_user or routing_number. Emitted by: MATCHED_SELECT_INSTITUTION
routing_number
nullablestring
The routing number submitted by user at the micro-deposits routing number pane. Emitted by SUBMIT_ROUTING_NUMBER.
mfa_type
nullablestring
If set, the user has encountered one of the following MFA types: code, device, questions, selections. Emitted by: SUBMIT_MFA and TRANSITION_VIEW when view_name is MFA
view_name
nullablestring
The name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW.
ACCEPT_TOS
The view showing Terms of Service in the identity verification flow.
CONNECTED
The user has connected their account.
CONSENT
We ask the user to consent to the privacy policy.
CREDENTIAL
Asking the user for their account credentials.
DATA_TRANSPARENCY
We disclose the data types being shared.
DATA_TRANSPARENCY_CONSENT
We ask the user to consent to the privacy policy and disclose data types being shared.
DOCUMENTARY_VERIFICATION
The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor).
ERROR
An error has occurred.
EXIT
Confirming if the user wishes to close Link.
KYC_CHECK
The view representing the "know your customer" step in the identity verification flow.
LOADING
Link is making a request to our servers.
MATCHED_CONSENT
We ask the matched user to consent to the privacy policy and SMS terms.
MATCHED_CREDENTIAL
We ask the matched user for their account credentials to a matched institution.
MATCHED_MFA
We ask the matched user for MFA authentication to verify their identity.
MFA
The user is asked by the institution for additional MFA authentication.
NUMBERS
The user is asked to insert their account and routing numbers.
OAUTH
The user is informed they will authenticate with the financial institution via OAuth.
RECAPTCHA
The user was presented with a Google reCAPTCHA to verify they are human.
RISK_CHECK
The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor).
SCREENING
The watchlist screening step in the identity verification flow.
SELECT_ACCOUNT
We ask the user to choose an account.
SELECT_AUTH_TYPE
The user is asked to choose whether to Link instantly or manually (i.e., with micro-deposits).
SELECT_BRAND
The user is asked to select a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.
SELECT_INSTITUTION
We ask the user to choose their institution.
SELFIE_CHECK
The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.
UPLOAD_DOCUMENTS
The user is asked to upload documents (for Income verification).
VERIFY_SMS
The SMS verification step in the identity verification flow.
request_id
string
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
link_session_id
string
The link_session_id is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: all events.
timestamp
string
An ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z. Emitted by: all events.
selection
nullablestring
Either the verification method for a matched institution selected by the user or the Auth Type Select flow type selected by the user. If selection is used to describe selected verification method, then possible values are phoneotp or password; if selection is used to describe the selected Auth Type Select flow, then possible values are flow_type_manual or flow_type_instant. Emitted by: MATCHED_SELECT_VERIFY_METHOD and SELECT_AUTH_TYPE.
1const handler = Plaid.create({
2  ...,
3  onEvent: (eventName, metadata) => {
4    // send event and metadata to self-hosted analytics
5    analytics.send(eventName, metadata);
6  },
7});
1{
2  error_type: 'ITEM_ERROR',
3  error_code: 'INVALID_CREDENTIALS',
4  error_message: 'the credentials were not correct',
5  exit_status: null,
6  institution_id: 'ins_4',
7  institution_name: 'Wells Fargo',
8  institution_search_query: 'wellsf',
9  mfa_type: null,
10  view_name: 'ERROR'
11  request_id: 'm8MDnv9okwxFNBV',
12  link_session_id: '30571e9b-d6c6-42ee-a7cf-c34768a8f62d',
13  timestamp: '2017-09-14T14:42:19.350Z',
14}

open()

Calling open will display the Consent Pane view to your user, starting the Link flow. Once open is called, you will begin receiving events via the onEvent callback.

1const handler = Plaid.create({ ... });
2
3// Open Link
4handler.open();

exit()

The exit function allows you to programmatically close Link. Calling exit will trigger either the onExit or onSuccess callbacks.
The exit function takes a single, optional argument, a configuration Object.

exit
force
boolean
If true, Link will exit immediately. If false, or the option is not provided, an exit confirmation screen may be presented to the user.
1const handler = Plaid.create({ ... });
2
3// Graceful exit - Link may display a confirmation screen
4// depending on how far the user is in the flow
5handler.exit();
1const handler = Plaid.create({ ... });
2
3// Force exit - Link exits immediately
4handler.exit({ force: true });

destroy()

The destroy function allows you to destroy the Link handler instance, properly removing any DOM artifacts that were created by it. Use destroy() when creating new replacement Link handler instances in the onExit callback.

1const handler = Plaid.create({ ... })
2
3// Destroy and clean up the Link handler & iFrame
4handler.destroy();

Plaid Link for iOS

This section provides instructions for maintaining Plaid integrations using the deprecated public_key parameter. These instructions cannot be used for new integrations or for adding OAuth support to existing integrations. For up-to-date content on this topic, see the Link iOS SDK instead. For instructions on updating an existing legacy integration, see the Link token migration guide.

Overview

Here you find instructions on how to integrate and use Plaid Link for iOS. At the center of it lies LinkKit.framework: an embeddable framework managing the details of linking an account with Plaid.

To get up and running quickly with Plaid Link for iOS clone the GitHub repository and try out the example applications, which provide a reference implementation in Swift and Objective-C. Youʼll want to sign up for free API keys to get started.

Installation

Plaid Link for iOS is an embeddable framework that is bundled and distributed within your application. There are several ways to obtain the necessary files and keep them up-to-date; we recommend using CocoaPods or Carthage. Regardless of what you choose, submitting a new version of your application with the updated LinkKit.framework to the App Store is required.

Requirements

A new version of LinkKit.framework will be released around the 15th of every month. We recommend you keep up to date to provide the best Plaid Link experience in your application.

CocoaPods
  1. If you haven't already, install the latest version of CocoaPods.
  2. If you don't have an existing Podfile, run the following command to create one:
    1pod init
  3. Add this line to your Podfile:
    1pod 'Plaid'
  4. Run the following command:
    1pod install
  5. Add a custom Run Script build phase (we recommend naming it Prepare for Distribution ) with the script below, which prepares the LinkKit.framework for distribution through the App Store.
    Select Language
    1LINK_ROOT=${PODS_ROOT:+$PODS_ROOT/Plaid/ios}
    2cp "${LINK_ROOT:-$PROJECT_DIR}"/LinkKit.framework/prepare_for_distribution.sh "${CODESIGNING_FOLDER_PATH}"/Frameworks/LinkKit.framework/prepare_for_distribution.sh
    3"${CODESIGNING_FOLDER_PATH}"/Frameworks/LinkKit.framework/prepare_for_distribution.sh
  6. To update to newer releases in the future run:
    1pod install
Carthage
  1. If you haven't already, install the latest version of Carthage.
  2. If you don't have an existing Podfile, run the following command to create one:
    1pod init
  3. Add this line to your Podfile:
    1github "plaid/plaid-link-ios"
  4. Add a custom Run Script build phase (we recommend naming it Prepare for Distribution) with the script below, which prepares the LinkKit.framework for distribution through the App Store.
    Select Language
    1LINK_ROOT=${PODS_ROOT:+$PODS_ROOT/Plaid/ios}
    2cp "${LINK_ROOT:-$PROJECT_DIR}"/LinkKit.framework/prepare_for_distribution.sh "${CODESIGNING_FOLDER_PATH}"/Frameworks/LinkKit.framework/prepare_for_distribution.sh
    3"${CODESIGNING_FOLDER_PATH}"/Frameworks/LinkKit.framework/prepare_for_distribution.sh
  5. To update to newer releases in the future run:
    1carthage update plaid-ios --platform ios
Manual

Get the latest version of LinkKit.framework and embed it into your application.

Embed LinkKit.framework into your application, for example by dragging and dropping the file onto the Embed Frameworks build phase as shown below.

Depending on the location of the LinkKit.framework on the filesystem you may need to change the Framework Search Paths build setting to avoid the error: fatal error: 'LinkKit/LinkKit.h' file not found. For example, the LinkDemo Xcode projects have it set to FRAMEWORK_SEARCH_PATHS = $(PROJECT_DIR)/../ since the LinkKit.framework file is shared between them and is kept in the directory that also contains the demo project directories.

Finally, add a Run Script build phase (we recommend naming it Prepare for Distribution) with the script below. Be sure to run this build phase after the Embed Frameworks build phase or [CP] Embed Pods Frameworks build phase when integrating using CocoaPods, otherwise LinkKit.framework will not be properly prepared for distribution.

Failing to execute the run script build phase after the embed frameworks build phase very likely get your application rejected during App Store submission or review.

The script below removes from the framework any non-iOS device code that is included to support running LinkKit in the Simulator but that may not be distributed via the App Store.

Failing to run the script below will very likely get your application rejected during App Store submission or review.

Change the \${PROJECT_DIR\}/LinkKit.framework path in the example below according to your setup, and be sure to quote the filepaths when they contain whitespace.

1LINK_ROOT=\${PODS_ROOT:+$PODS_ROOT/Plaid/ios\}
2cp "\${LINK_ROOT:-$PROJECT_DIR\}"/LinkKit.framework/prepare_for_distribution.sh "\${CODESIGNING_FOLDER_PATH\}"/Frameworks/LinkKit.framework/prepare_for_distribution.sh
3"\${CODESIGNING_FOLDER_PATH\}"/Frameworks/LinkKit.framework/prepare_for_distribution.sh

Implementation

To use Plaid Link for iOS import LinkKit and its symbols into your code.

Select Language
1import LinkKit
2
3extension ViewController : PLKPlaidLinkViewDelegate {
4
5  // call presentPlaidLink to create + initialize Link
6  func presentPlaidLink() {
7    let linkViewController = PLKPlaidLinkViewController(configuration: PLKConfiguration(...), delegate: self)
8    present(linkViewController, animated: true)
9  }
10
11  // handle didSucceedWithPublicToken delegate method
12  func linkViewController(
13    _ linkViewController: PLKPlaidLinkViewController,
14    didSucceedWithPublicToken publicToken: String,
15    metadata: [String : Any]?) { /* handle success */ }
16
17  // handle didExitWithError delegate method
18  func linkViewController(
19    _ linkViewController: PLKPlaidLinkViewController,
20    didExitWithError error: Error?,
21    metadata: [String : Any]?) { /* handle exit | error */ }
22
23  // handle didHandleEvent delegate method
24  func linkViewController(
25    _ linkViewController: PLKPlaidLinkViewController,
26    didHandleEvent event: String,
27    metadata: [String : Any]?) { /* handle exit | error */ }
28}

Configure & present Link

Starting the Plaid Link for iOS experience is as simple as creating and presenting an instance of PLKPlaidLinkViewController. Then, create an instance of PLKConfiguration and pass that during the initialization of the PLKPlaidLinkViewController.

create_legacy
env
String
The Plaid API environment on which to create user accounts. Valid environments are:
  • .sandbox
  • .development
  • .production
key
String
The public_key associated with your account; available in the Plaid Dashboard.
product
[String]
A list of one or many Plaid product(s) you wish to use. Valid products are:
  • .auth
  • .transactions
  • .identity
  • .assets
  • .investments
  • .liabilities
  • .payment_initiation

Example: [.auth, .transactions]. .balance is not a valid value, the Balance product does not require explicit initialization and will automatically be initialized when any other product is initialized. Only institutions that support all requested products will be shown in Link.
In Production, you will be billed for each product that you specify when initializing Link. Note that a product cannot be removed from an Item once the Item has been initialized with that product. To stop billing on an Item for subscription-based products, such as Liabilities, Investments, and Transactions, remove the Item via /item/remove.
clientName
String
Displayed once a user has successfully linked their Item.
language
nullableString
Specify a Plaid-supported language to localize Link. English will be used by default. Supported languages:
  • English ('en')
  • French ('fr')
  • Spanish ('es')
  • Dutch ('nl')
When using a Link customization profile, language must be set to match the language used in the customization profile.
countryCodes
nullable[String]
Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard. Note that if you initialize with a European country code, your users will see the European consent panel during the Link flow. Supported country codes are:
  • US
  • CA
  • ES
  • FR
  • GB
  • IE
  • NL

If not specified, will default to ['US']. If Link is launched with multiple countryCodes, only products that you are enabled for in all countries will be used by Link.
If a Link customization is being used, the countries configured here should match those in the customization.
To use the Auth features Instant Match, Automated Micro-deposits, or Same-day Micro-deposits, countryCodes must be set to ['US'].
accountSubtypes
Dictionary
By default, Link will only display account types that are compatible with all products supplied in the product parameter. You can further limit the accounts shown in Link by using accountSubtypes to specify the account subtypes to be shown in Link. Only the specified subtypes will be shown. To indicate that all subtypes should be shown, use the value "all". If the accountSubtypes filter is used, any account type for which a filter is not specified will be entirely omitted from Link.
Example value:
{
"depository": ["checking", "savings"],
"credit": ["all"]
}
For a full list of valid types and subtypes, see the Account schema.
For institutions using OAuth, the filter will not affect the list of institutions shown by the bank in the OAuth window.
webhook
String
Specify a webhook to associate with an Item. Plaid fires a webhook when the Item requires updated credentials, when new data is available, or when Auth numbers have been successfully verified.
linkCustomizationName
String
Specify the name of a Link customization created in the Dashboard. The default customization is used if none is provided. When using a Link customization, the language specified in the customization must match the language configured via the language parameter.
oauthNonce
String
An oauthNonce is required to support OAuth authentication flows when launching or re-launching Link on a mobile device and using one or more European country codes. The nonce must be at least 16 characters long.
oauthRedirectUri
String
An oauthRedirectUri is required to support OAuth authentication flows when launching Link on a mobile device and using one or more European country codes. Any redirect URI must also be added to the Allowed redirect URIs list in the developer dashboard. For mobile app integrations, the redirect URI must be registered as an app link (not custom URI) to enable app-to-app authentication flows. You will need to configure an Android App Link or Apple App Association File. Custom URI schemes are not supported; a proper universal link must be used.
oauthStateId
String
An oauthStateId is required to support OAuth authentication flows when re-launching Link on a mobile device and using one or more European country codes.
paymentToken
String
A paymentToken must be specified if you are using the Payment Initiation (UK and Europe) product. This will cause Link to open directly to the Payment Initiation flow. Use the /payment_initiation/payment/token/create endpoint to generate a payment_token.
Select Language
1let linkConfiguration = PLKConfiguration(
2  env: .sandbox,
3  key: "<YOUR_PLAID_PUBLIC_KEY>",
4  product: [.auth]
5)
6linkConfiguration.clientName = "My application";
7linkConfiguration.language = "en";
8linkConfiguration.countryCodes = ["US", "CA", "GB"];
9linkConfiguration.webhook = "https://webhook.com";
10linkConfiguration.linkCustomizationName = "default";
11linkConfiguration.oauthRedirectUri = "<YOUR_OAUTH_REDIRECT_URI>"
12linkConfiguration.oauthNonce = UUID().uuidString
13
14let linkViewController = PLKPlaidLinkViewController(
15  configuration: linkConfiguration,
16  delegate: self
17)
18
19present(linkViewController, animated: true)

didSucceedWithPublicToken

The closure is called when a user successfully links an Item. It should take a single LinkSuccess argument, containing the publicToken String and a metadata of type SuccessMetadata.

onSuccess
linkSuccess
LinkSuccess
Contains the publicToken and metadata for this successful flow.
publicToken
String
Displayed once a user has successfully linked their Item.
metadata
LinkSuccess
Displayed once a user has successfully linked their Item.
institution
nullableInstitution
An institution object. If the Item was created via Same-Day micro-deposit verification, will be null.
name
String
The full institution name, such as 'Wells Fargo'
institutionID
InstitutionID (String)
The Plaid institution identifier
accounts
Array<Account>
A list of accounts attached to the connected Item
id
AccountID (String)
The Plaid account_id
name
String
The official account name
mask
Optional<AccountMask> (Optional<String>)
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, it may also not match the mask that the bank displays to the user.
subtype
AccountSubtype
The account subtype and its type. See Account Types for a full list of possible values.
verificationStatus
Optional<VerificationStatus>
The Item's micro-deposit-based verification status. Possible values are:
pending_automatic_verification: The Item is pending automatic verification.
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the two amounts.
automatically_verified: The Item has successfully been automatically verified.
manually_verified: The Item has successfully been manually verified.
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.
nil: Micro-deposit-based verification is not being used for the Item.
linkSessionID
String
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
metadataJSON
String
Unprocessed metadata, formatted as JSON, sent from the Plaid API.
Select Language
1func linkViewController(
2  _ linkViewController: PLKPlaidLinkViewController,
3  didSucceedWithPublicToken publicToken: String,
4  metadata: [String : Any]?
5) {
6  dismiss(animated: true) {
7  // Exchange publicToken with an accessToken on your server
8    NSLog("Successfully linked account!\npublicToken: (publicToken)\nmetadata: (metadata ?? [:])")
9  }
10}
1{
2  kPLKMetadataInstitutionKey: @{
3    kPLKMetadataInstitutionNameKey: 'Wells Fargo',
4    kPLKMetadataInstitutionIdKey: 'ins_4'
5  },
6  kPLKMetadataAccountsKey: [
7    @{
8      kPLKMetadataIdKey: 'ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy',
9      kPLKMetadataNameKey: 'Plaid Checking',
10      kPLKMetadataMaskKey: '0000',
11      kPLKMetadataTypeKey: 'depository',
12      kPLKMetadataSubtypeKey: 'checking',
13      kPLKMetadataAccountVerificationStatusKey: ''
14    },
15    @{
16      kPLKMetadataIdKey: '9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4',
17      kPLKMetadataNameKey: 'Plaid Saving',
18      kPLKMetadataMaskKey: '1111',
19      kPLKMetadataTypeKey: 'depository',
20      kPLKMetadataSubtypeKey: 'savings'
21    }
22    ...
23  ],
24  kPLKMetadataLinkSessionIdKey: '79e772be-547d-4c9c-8b76-4ac4ed4c441a'
25}

didExitWithError

This optional closure is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. It should take a single LinkExit argument, containing an optional error and a metadata of type ExitMetadata.

onExit
linkExit
LinkExit
Contains the optional error and metadata for when the flow was exited.
error
Optional<ExitError> (Swift), Optional<NSError> (Objective-C)
An Error type that contains the errorCode, errorMessage, and displayMessage of the error that was last encountered by the user. If no error was encountered, error will be nil. In Objective-C, field names will match the NSError type.
errorCode
ExitErrorCode
The error code and error type that the user encountered. Each errorCode has an associated errorType, which is a broad categorization of the error.
errorMessage
String
A developer-friendly representation of the error code.
displayMessage
Optional<String>
A user-friendly representation of the error code or nil if the error is not related to user action. This may change over time and is not safe for programmatic use.
metadata
ExitMetadata
Displayed once a user has successfully linked their Item.
status
Optional<ExitStatus>
The status key indicates the point at which the user exited the Link flow.
requiresQuestions
User prompted to answer security question(s).
requiresSelections
User prompted to answer multiple choice question(s).
requiresCode
User prompted to provide a one-time passcode.
chooseDevice
User prompted to select a device on which to receive a one-time passcode.
requiresCredentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution.
requiresAccountSelection
User prompted to select one or more financial accounts to share
institutionNotFound
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
unknown
The exit status has not been defined in the current version of the SDK. The unknown case has an associated value carrying the original exit status as sent by the Plaid API.
institution
Optional<Institution>
An institution object. If the Item was created via Same-Day micro-deposit verification, will be omitted.
institutionID
InstitutionID (String)
The Plaid specific identifier for the institution.
name
String
The full institution name, such as 'Wells Fargo'.
linkSessionID
Optional<String>
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
requestID
Optional<String>
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation.
metadataJSON
RawJSONMetadata (String)
Unprocessed metadata, formatted as JSON, sent from Plaid API.
Select Language
1func linkViewController(
2    _ linkViewController: PLKPlaidLinkViewController,
3  didExitWithError error: Error?,
4                metadata: [String : Any]?
5) {
6  dismiss(animated: true) {
7    if let error = error {
8      NSLog("Failed to link account due to: (error.localizedDescription)\n metadata: (metadata ?? [:])")
9      self.handleError(error, metadata: metadata)
10    }
11    else {
12      NSLog("Plaid link exited with metadata: (metadata ?? [:])")
13      self.handleExitWithMetadata(metadata)
14    }
15  }
16}
Select Language
1{
2  kPLKErrorTypeKey: 'ITEM_ERROR',
3  kPLKErrorCodeKey: 'INVALID_CREDENTIALS',
4  kPLKErrorMessageKey: 'the credentials were not correct',
5  kPLKDisplayMessageKey: 'The credentials were not correct.',
6}
Select Language
1{
2   kPLKMetadataInstitutionKey: @{
3    kPLKMetadataInstitutionNameKey: 'Wells Fargo',
4    kPLKMetadataInstitutionIdKey: 'ins_4'
5  },
6  kPLKMetadataLinkSessionIdKey: '36e201e0-2280-46f0-a6ee-6d417b450438',
7  kPLKMetadataRequestIdKey: '8C7jNbDScC24THu'
8}

didHandleEvent

This optional closure is called when certain events in the Plaid Link flow have occurred, for example, when the user selected an institution. This enables your application to gain further insight into what is going on as the user goes through the Plaid Link flow.
The following onEvent callbacks are stable, which means that they will not be deprecated or changed: open, exit, handoff, selectInstitution, error, bankIncomeInsightsCompleted, identityVerificationPassSession, identityVerificationFailSession. The remaining callback events are informational and subject to change.

onEvent
linkEvent
LinkEvent
Contains the eventName and metadata for the Link event.
eventName
EventName
An enum representing the event that has just occurred in the Link flow.
bankIncomeInsightsCompleted
The user has completed the Assets and Bank Income Insights flow.
closeOAuth
The user closed the third-party website or mobile app without completing the OAuth flow.
error
A recoverable error occurred in the Link flow, see the errorCode in the `metadata.
exit
The user has exited without completing the Link flow and the onExit callback is fired.
failOAuth
The user encountered an error while completing the third-party's OAuth login flow.
handoff
The user has exited Link after successfully linking an Item.
identityVerificationStartStep
The user has started a step of the Identity Verification flow. The step is indicated by view_name.
identityVerificationPassStep
The user has passed a step of the Identity Verification flow. The step is indicated by view_name.
identityVerificationFailStep
The user has failed a step of the Identity Verification flow. The step is indicated by view_name.
identityVerificationReviewStep
The user has reached the pending review state.
identityVerificationCreateSession
The user has started a new Identity Verification session.
identityVerificationResumeSession
The user has resumed an existing Identity Verification session.
identityVerificationPassSession
The user has successfully completed their Identity Verification session.
identityVerificationFailSession
The user has failed their Identity Verification session.
identityVerificationPendingReviewSession
The user has completed their Identity Verification session, which is now in a pending review state.
identityVerificationOpenUI
The user has opened the UI of their Identity Verification session.
identityVerificationResumeUI
The user has resumed the UI of their Identity Verification session.
identityVerificationCloseUI
The user has closed the UI of their Identity Verification session.
matchedSelectInstitution
The user selected an institution that was presented as a matched institution. This event can be emitted either during the Returning User Experience flow or if the institution's routing_number was provided when calling /link/token/create. To distinguish between the two scenarios, see metadata.matchReason.
matchedSelectVerifyMethod
The user selected a verification method for a matched institution. This event is emitted only during the Returning User Experience flow.
open
The user has opened Link.
openMyPlaid
The user has opened my.plaid.com. This event is only sent when Link is initialized with Assets as a product.
openOAuth
The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.
searchInstitution
The user has searched for an institution.
selectBrand
The user selected a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.
selectInstitution
The user selected an institution.
submitCredentials
The user has submitted credentials.
submitMFA
The user has submitted MFA.
transitionView
The transitionView event indicates that the user has moved from one view to the next.
viewDataTypes
The user has viewed data types on the data transparency consent pane.
unknown
The event has not been defined in the current version of the SDK. The unknown case has an associated value carrying the original event name as sent by the Plaid API.
metadata
EventMetadata struct
An object containing information about the event
accountNumberMask
Optional<String>
The account number mask extracted from the user-provided account number. If the user-inputted account number is four digits long, account_number_mask is empty. Emitted by SUBMIT_ACCOUNT_NUMBER.
errorCode
Optional<ExitErrorCode>
The error code that the user encountered. Emitted by: error, exit.
errorMessage
Optional<String>
The error message that the user encountered. Emitted by: error, exit.
exitStatus
Optional<ExitStatus>
The status key indicates the point at which the user exited the Link flow. Emitted by: exit.
requiresQuestions
User prompted to answer security question(s).
requiresSelections
User prompted to answer multiple choice question(s).
requiresCode
User prompted to provide a one-time passcode.
chooseDevice
User prompted to select a device on which to receive a one-time passcode.
requiresCredentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution.
institutionNotFound
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
unknown
The exit status has not been defined in the current version of the SDK. The unknown case has an associated value carrying the original exit status as sent by the Plaid API.
institutionID
Optional<InstitutionID> (Optional<String>)
The ID of the selected institution. Emitted by: all events.
institutionName
Optional<String>
The name of the selected institution. Emitted by: all events.
institutionSearchQuery
Optional<String>
The query used to search for institutions. Emitted by: searchInstitution.
isUpdateMode
Optional<String>
Indicates if the current Link session is an update mode session. Emitted by: OPEN.
matchReason
nullablestring
The reason this institution was matched, which will be either returning_user or routing_number. Emitted by: matchedSelectInstitution.
linkSessionID
String
The link_session_id is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: all events.
mfaType
Optional<MFAType>
If set, the user has encountered one of the following MFA types: code, device, questions, selections. Emitted by: submitMFA and transitionView when viewName is mfa
requestID
Optional<String>
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
routingNumber
Optional<String>
The routing number submitted by user at the micro-deposits routing number pane. Emitted by SUBMIT_ROUTING_NUMBER.
selection
Optional<String>
Either the verification method for a matched institution selected by the user or the Auth Type Select flow type selected by the user. If selection is used to describe selected verification method, then possible values are phoneotp or password; if selection is used to describe the selected Auth Type Select flow, then possible values are flow_type_manual or flow_type_instant. Emitted by: MATCHED_SELECT_VERIFY_METHOD and SELECT_AUTH_TYPE.
timestamp
Date
An ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z. Emitted by: all events.
viewName
Optional<ViewName>
The name of the view that is being transitioned to. Emitted by: transitionView.
acceptTOS
The view showing Terms of Service in the identity verification flow.
connected
The user has connected their account.
consent
We ask the user to consent to the privacy policy.
credential
Asking the user for their account credentials.
dataTransparency
We disclose the data types being shared.
dataTransparencyConsent
We ask the user to consent to the privacy policy and disclose data types being shared.
documentaryVerification
The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor).
error
An error has occurred.
exit
Confirming if the user wishes to close Link.
kycCheck
The view representing the "know your customer" step in the identity verification flow.
loading
Link is making a request to our servers.
matchedConsent
We ask the matched user to consent to the privacy policy and SMS terms.
matchedCredential
We ask the matched user for their account credentials to a matched institution.
matchedMfa
We ask the matched user for MFA authentication to verify their identity.
mfa
The user is asked by the institution for additional MFA authentication.
numbers
The user is asked to insert their account and routing numbers.
oauth
The user is informed they will authenticate with the financial institution via OAuth.
recaptcha
The user was presented with a Google reCAPTCHA to verify they are human.
riskCheck
The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor).
screening
The watchlist screening step in the identity verification flow.
selectAccount
We ask the user to choose an account.
selectAuthType
The user is asked to choose whether to Link instantly or manually (i.e., with micro-deposits).
selectBrand
The user is asked to select a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.
selectInstitution
We ask the user to choose their institution.
selfieCheck
The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.
uploadDocuments
The user is asked to upload documents (for Income verification).
verifySMS
The SMS verification step in the identity verification flow.
unknown
The view has not been defined in the current version of the SDK. The unknown case has an associated value carrying the original view name as sent by the Plaid API.
metadataJSON
RawJSONMetadata (String)
Unprocessed metadata, formatted as JSON, sent from Plaid API.
Select Language
1func linkViewController(
2  _ linkViewController: PLKPlaidLinkViewController,
3  didHandleEvent event: String,
4  metadata: [String : Any]?
5) {
6  NSLog("Link event: (event)\nmetadata: (metadata ?? [:])")
7}
Select Language
1{
2  kPLKMetadataErrorTypeKey: 'ITEM_ERROR',
3  kPLKMetadataErrorCodeKey: 'INVALID_CREDENTIALS',
4  kPLKMetadataErrorMessageKey: 'the credentials were not correct',
5  kPLKMetadataExitStatusKey: '',
6  kPLKMetadataInstitutionIdKey: 'ins_4',
7  kPLKMetadataInstitutionNameKey: 'Wells Fargo',
8  kPLKMetadataInstitutionSearchQueryKey: 'wellsf',
9  kPLKMetadataLinkSessionIdKey: '30571e9b-d6c6-42ee-a7cf-c34768a8f62d',
10  kPLKMetadataMFATypeKey: '',
11  kPLKMetadataRequestIdKey: 'm8MDnv9okwxFNBV',
12  kPLKMetadataTimestampKey: '2017-09-14T14:42:19.350Z',
13  kPLKMetadataViewNameKey: 'ERROR'
14}

Plaid Link for Android

This section provides instructions for maintaining Plaid integrations using the deprecated public_key parameter. These instructions cannot be used for new integrations or for adding OAuth support to existing integrations. For up-to-date content on this topic, see the Link Android SDK instead. For instructions on updating an existing legacy integration, see the Link token migration guide.

Overview

Here you find instructions on how to integrate and use Plaid Link for Android. At the center of it lies LinkSdk: an embeddable framework managing the details of linking an account with Plaid.

To get up and running quickly with Plaid Link for Android, clone the GitHub repository and try out the example applications, which provide a reference implementation in Java and Kotlin. Youʼll want to sign up for free API keys through the Plaid Developer Dashboard to get started.

Requirements

A new version of the Android SDK will be released around the 15th of every month. You should keep your version up-to-date to provide the best Plaid Link experience in your application.

Update your project plugins

In your root-level (project-level) Gradle file (build.gradle), add rules to include the Android Gradle plugin. Check that you have Google's Maven repository, as well.

1buildscript {
2    repositories {
3        // Check that you have the following line (if not, add it):
4        google()  // Google's Maven repository
5        mavenCentral() // Include to import Plaid Link Android SDK
6        jcenter() // Include to import Plaid Link transitive dependencies
7    }
8    dependencies {
9        // ...
10    }
11}
Add the PlaidLink SDK to your app

In your module (app-level) Gradle file (usually app/build.gradle), add a line to the bottom of the file. The latest version of the PlaidLink SDK is Maven Central and can be found on Maven Central.

1android {
2  defaultConfig {
3    minSdkVersion 21 // or greater
4  }
5
6  // Enable Java 8 support for Link to work
7  compileOptions {
8    sourceCompatibility JavaVersion.VERSION_1_8
9    targetCompatibility JavaVersion.VERSION_1_8
10  }
11}
12
13dependencies {
14  // ...
15  implementation 'com.plaid.link:sdk-core:<insert latest version>'
16}
Register your app ID

To register your Android app ID:

  1. Log in to the Plaid Dashboard
  2. Navigate to the API pane on the Team Settings page
  3. Configure one or more Android package names (e.g.com.plaid.example)
  4. Save your changes

Your Android app is now set up and ready to start integrating with the Plaid SDK.

Initialize Plaid Link Instance

Create an instance of Plaid Link by calling Plaid.initialize(application). Try to do this as early as possible to speed up opening Plaid Link.

Select Language
1import android.app.Application
2import com.plaid.link.Plaid
3
4class MyApplication : Application() {
5
6  override fun onCreate() {
7    super.onCreate()
8    Plaid.initialize(this)
9  }

Open Link

The Plaid object can be used to open Link with the given configuration. With Kotlin you can use the openPlaidLink extension function from an Activity or Fragment.

create_legacy
accountSubtypes
List
By default, Link will only display account types that are compatible with all products supplied in the product parameter. You can further limit the accounts shown in Link by using accountSubtypes to specify the account subtypes to be shown in Link. Only the specified subtypes will be shown. To indicate that all subtypes should be shown, use the value "all". If the accountSubtypes filter is used, any account type for which a filter is not specified will be entirely omitted from Link.
Example value:
{
"depository": ["checking", "savings"],
"credit": ["all"]
}
For a full list of valid types and subtypes, see the Account schema.
For institutions using OAuth, the filter will not affect the list of institutions shown by the bank in the OAuth window.
clientName
String
Displayed once a user has successfully linked their Item.
countryCodes
List
Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard. Accepted values must use the native Android Locale country. If Link is launched with multiple countryCodes only products that you are enabled for in all specified countries will be available. Supported countries:
  • Canada: Locale.CA.country
  • France: Locale.FR.country
  • Ireland: Locale.IE.country
  • Netherlands: Locale.NL.country
  • Spain: Locale.ES.country
  • United Kingdom: Locale.UK.country
  • United States: Locale.US.country
If a Link customization is being used, the countries configured here should match those in the customization.
To use the Auth features Instant Match, Automated Micro-deposits, or Same-day Micro-deposits, countryCodes must be set to [Locale.US.country].
environment
String
The Plaid API environment on which to create user accounts. Available environments
  • Sandbox: PlaidEnvironment.SANDBOX
  • Development: PlaidEnvironment.DEVELOPMENT
  • Production: PlaidEnvironment.PRODUCTION
language
String
Specify a Plaid-supported language to localize Link. Accepted values must use the native Android Locale Language. English will be used by default. Supported languages:
  • English: Locale.ENGLISH.language
  • French: Locale.FRENCH.language
  • Spanish: Locale.SPANISH.language
  • Dutch: Locale.DUTCH.language
When using a Link customization, language must be set to match the language used in the customization.
products
List
A list of Plaid product(s) you wish to use. Only institutions that support all requested products will be shown in Link. Valid products:
  • Auth: PlaidProduct.AUTH
  • Transactions: PlaidProduct.TRANSACTIONS
  • Identity: PlaidProduct.IDENTITY
  • Assets: PlaidProduct.ASSETS
  • Investments: PlaidProduct.INVESTMENTS
  • Liabilities: PlaidProduct.LIABILITIES
  • PaymentInitiation: PlaidProduct.PAYMENT_INITIATION

In Production, you will be billed for each product that you specify when initializing Link. Note that a product cannot be removed from an Item once the Item has been initialized with that product. To stop billing on an Item for subscription-based products, such as Liabilities, Investments, and Transactions, remove the Item via /item/remove.
linkCustomizationName
String
Specify the name of a Link customization created in the Dashboard. The default customization is used if none is provided. When using a Link customization, the language specified in the customization must match the language configured via the language parameter.
logLevel
enum
Set the level at which to log statements. Possible values are ASSERT, DEBUG, ERROR, INFO, VERBOSE, and WARN.
publicKey
String
The public_key associated with your account; available from the Dashboard.
token
string
Specify a payment_token or access_token. For link_token use a LinkTokenConfiguration instead.
userLegalName
string
The end user's legal name
userPhoneNumber
string
The end user's phone number
userEmailAddress
string
The end user's email address
webhook
String
Specify a webhook to associate with an Item. Plaid fires a webhook when the Item requires updated credentials, when new data is available, or when Auth numbers have been successfully verified.
extraParams
deprecatedmap<string, string>
Any additional params that need to be passed into the SDK can be added here.
Select Language
1import android.content.Intent
2import com.plaid.link.Plaid
3import com.plaid.linkbase.models.LinkConfiguration
4import com.plaid.linkbase.models.PlaidEnvironment
5import com.plaid.linkbase.models.PlaidProduct
6import com.plaid.link.configuration.LinkLogLevel
7
8class MainActivity : AppCompatActivity() {
9
10  override fun onCreate(savedInstanceState: Bundle?) {
11    super.onCreate(savedInstanceState)
12
13    // Open Link – this will usually be in a click listener
14    this@MainActivity.openPlaidLink(
15      linkConfiguration = linkConfiguration {
16        environment = PlaidEnvironment.SANDBOX
17        products = listOf(PlaidProduct.TRANSACTIONS)
18        clientName = "My Application name"
19        language = Locale.ENGLISH.language
20        countryCodes = listOf(Locale.US.country)
21        webhook = "https://requestb.in"
22        linkCustomizationName = "default"
23        publicToken = null
24        paymentToken = null
25      }
26    )
27  }
28}

Handling Results and Events

The onActivityResult handler is called for the onSuccess and onExit events. Use PlaidLinkResultHandler to parse the result out of the returned intent.

Select Language
1import android.content.Intent
2
3import com.plaid.link.LinkActivity
4import com.plaid.link.Plaid
5import com.plaid.linkbase.models.LinkEventListener
6import com.plaid.linkbase.models.PlaidApiError
7import com.plaid.linkbase.models.PlaidEnvironment
8import com.plaid.linkbase.models.PlaidProduct
9
10class MainActivity : AppCompatActivity() {
11
12  private val resultHandler = PlaidLinkResultHandler(
13    onSuccess = { it: LinkConnection -> /* handle onSuccess */ }
14    onExit = { it: PlaidError -> /* handle onExit */ }
15  )
16
17  override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
18    super.onActivityResult(requestCode, resultCode, data)
19    if (!resultHandler.onActivityResult(requestCode, resultCode, data)) {
20      Log.i(MainActivity.class.getSimpleName(), "Not handled");
21    }
22  }
23
24  override fun onCreate(savedInstanceState: Bundle?) {
25    super.onCreate(savedInstanceState)
26
27    Plaid.setLinkEventListener { event -> Log.i("Event", event.toString()) }
28
29    ...
30  }
31}

onSuccess

The method is called when a user successfully links an Item. The onSuccess handler returns a LinkConnection class that includes the public_token, and additional Link metadata in the form of a LinkConnectionMetadata class.

onSuccess
publicToken
String
Displayed once a user has successfully linked their Item.
metadata
Object
Displayed once a user has successfully linked their Item.
accounts
List<LinkAccount>
A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, accounts will only include selected accounts.
id
string
The Plaid account_id
name
string
The official account name
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, it may also not match the mask that the bank displays to the user.
subtype
LinkAccountSubtype
The account subtype. See the Account schema for a full list of possible values
type
LinkAccountType
The account type. See the Account schema for a full list of possible values
verification_status
nullablestring
The accounts object includes an Item's micro-deposit verification status. Possible values are:
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the two amounts.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.
null: The Item is not using micro-deposit verification.
institution
nullableobject
An institution object. If the Item was created via Same-Day micro-deposit verification, will be null.
name
string
The full institution name, such as 'Wells Fargo'
institution_id
string
The Plaid institution identifier
linkSessionId
nullableString
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
metadataJson
nullableMap
The data directly returned from the server with no client side changes.
Select Language
1class MainActivity : AppCompatActivity() {
2
3  private val resultHandler = PlaidLinkResultHandler(
4    // ...
5    onSuccess = { it: LinkConnection ->
6      // Send public_token to your server, exchange for access_token
7      val publicToken = it.publicToken
8
9      val metadata = it.linkConnectionMetadata
10      val accountId = metadata.accounts.first().accountId
11      val accountName = metadata.accounts.first().accountName
12      val accountNumber = metadata.accounts.first().accountNumber
13      val accountType = metadata.accounts.first().accountType
14      val accountSubType = metadata.accounts.first().accountSubType
15      val institutionId = metadata.institutionId
16      val institutionName = metadata.institutionName
17    }
18  )
19}

onExit

The onExit handler is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The PlaidError returned from the onExit handler is meant to help you guide your users after they have exited Link. We recommend storing the error and metadata information server-side in a way that can be associated with the user. You’ll also need to include this and any other relevant information in Plaid Support requests for the user.

onExit
error
Map<String, Object>
An object that contains the error type, error code, and error message of the error that was last encountered by the user. If no error was encountered, error will be null.
displayMessage
nullableString
A user-friendly representation of the error code. null if the error is not related to user action. This may change over time and is not safe for programmatic use.
errorCode
String
The particular error code. Each errorType has a specific set of errorCodes. A code of 499 indicates a client-side exception.
json
String
A string representation of the error code.
errorType
String
A broad categorization of the error.
errorMessage
String
A developer-friendly representation of the error code.
errorJson
nullableString
The data directly returned from the server with no client side changes.
LinkExitMetadata
Map<String, Object>
An object containing information about the exit event
linkSessionId
nullableString
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
institution
nullableobject
An institution object. If the Item was created via Same-Day micro-deposit verification, will be null.
name
string
The full institution name, such as 'Wells Fargo'
institution_id
string
The Plaid institution identifier
status
nullableString
The point at which the user exited the Link flow. One of the following values.
requires_questions
User prompted to answer security questions
requires_selections
User prompted to answer multiple choice question(s)
requires_recaptcha
User prompted to solve a reCAPTCHA challenge
requires_code
User prompted to provide a one-time passcode
choose_device
User prompted to select a device on which to receive a one-time passcode
requires_credentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution
requires_account_selection
User prompted to select one or more financial accounts to share
institution_not_found
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
unknown
An exit status that is not handled by the current version of the SDK
requestId
nullableString
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation
Select Language
1class MainActivity : AppCompatActivity() {
2
3  private val resultHandler = PlaidLinkResultHandler(
4    // ...
5    onExit = {
6      PlaidError error = it.error?
7      String errorType = error.errorType
8      String errorCode = error.errorCode
9      String errorMessage = error.errorMessage
10      String displayMessage = error.displayMessage
11
12      LinkExitMetadata metadata = it.linkExitMetadata
13      String institutionId = metadata.institutionId
14      String institutionName = metadata.institutionName
15      String linkSessionId = metadata.linkSessionId;
16      String requestId = metadata.requestId;
17    },
18  )
19}

onEvent

The onEvent callback is called at certain points in the Link flow. Unlike the handlers for onSuccess and onExit, the onEvent handler is initialized as a global lambda passed to the Plaid class. OPEN events will be sent immediately upon Link’s opening, and remaining events will be sent by the time onSuccess or onExit is called. If you need the exact time when an event happened, use the timestamp property.
The following onEvent callbacks are stable, which means that they will not be deprecated or changed: OPEN, EXIT, HANDOFF, SELECT_INSTITUTION, ERROR, BANK_INCOME_INSIGHTS_COMPLETED, IDENTITY_VERIFICATION_PASS_SESSION, IDENTITY_VERIFICATION_FAIL_SESSION. The remaining callback events are informational and subject to change.

onEvent
eventName
String
A string representing the event that has just occurred in the Link flow.
BANK_INCOME_INSIGHTS_COMPLETED
The user has completed the Assets and Bank Income Insights flow.
CLOSE_OAUTH
The user closed the third-party website or mobile app without completing the OAuth flow.
ERROR
A recoverable error occurred in the Link flow, see the error_code metadata.
EXIT
The user has exited without completing the Link flow and the onExit callback is fired.
FAIL_OAUTH
The user encountered an error while completing the third-party's OAuth login flow.
HANDOFF
The user has exited Link after successfully linking an Item.
IDENTITY_VERIFICATION_START_STEP
The user has started a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_PASS_STEP
The user has passed a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_FAIL_STEP
The user has failed a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_PENDING_REVIEW_STEP
The user has reached the pending review state.
IDENTITY_VERIFICATION_CREATE_SESSION
The user has started a new Identity Verification session.
IDENTITY_VERIFICATION_RESUME_SESSION
The user has resumed an existing Identity Verification session.
IDENTITY_VERIFICATION_PASS_SESSION
The user has successfully completed their Identity Verification session.
IDENTITY_VERIFICATION_FAIL_SESSION
The user has failed their Identity Verification session.
IDENTITY_VERIFICATION_PENDING_REVIEW_SESSION
The user has completed their Identity Verification session, which is now in a pending review state.
IDENTITY_VERIFICATION_OPEN_UI
The user has opened the UI of their Identity Verification session.
IDENTITY_VERIFICATION_RESUME_UI
The user has resumed the UI of their Identity Verification session.
IDENTITY_VERIFICATION_CLOSE_UI
The user has closed the UI of their Identity Verification session.
MATCHED_SELECT_INSTITUTION
The user selected an institution that was presented as a matched institution. This event can be emitted either during the Returning User Experience flow or if the institution's routing_number was provided when calling /link/token/create. To distinguish between the two scenarios, see LinkEventMetadata.match_reason.
MATCHED_SELECT_VERIFY_METHOD
The user selected a verification method for a matched institution. This event is emitted only during the Returning User Experience flow.
OPEN
The user has opened Link.
OPEN_MY_PLAID
The user has opened my.plaid.com. This event is only emitted when Link is initialized with Assets as a product.
OPEN_OAUTH
The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.
SEARCH_INSTITUTION
The user has searched for an institution.
SELECT_BRAND
The user selected a brand, e.g. Bank of America. The SELECT_BRAND event is only emitted for large financial institutions with multiple online banking portals.
SELECT_DEGRADED_INSTITUTION
The user selected an institution with a DEGRADED health status and was shown a corresponding message.
SELECT_DOWN_INSTITUTION
The user selected an institution with a DOWN health status and was shown a corresponding message.
SELECT_INSTITUTION
The user selected an institution.
SUBMIT_ACCOUNT_NUMBER
The user has submitted an account number. This event emits the account_number_mask metadata to indicate the mask of the account number the user provided.
SUBMIT_CREDENTIALS
The user has submitted credentials.
SUBMIT_MFA
The user has submitted MFA.
SUBMIT_ROUTING_NUMBER
The user has submitted routing number. This event emits the routing_number metadata to indicate user's routing number.
TRANSITION_VIEW
The TRANSITION_VIEW event indicates that the user has moved from one view to the next.
UPLOAD_DOCUMENTS
The user is asked to upload documents (for Income verification).
VIEW_DATA_TYPES
The user has viewed data types on the data transparency consent pane.
UNKNOWN
The UNKNOWN event indicates that the event is not handled by the current version of the SDK.
LinkEventMetadata
Map<String, Object>
An object containing information about the event.
accountNumberMask
String
The account number mask extracted from the user-provided account number. If the user-inputted account number is four digits long, account_number_mask is empty. Emitted by SUBMIT_ACCOUNT_NUMBER.
errorCode
String
The error code that the user encountered. Emitted by: ERROR, EXIT.
errorMessage
String
The error message that the user encountered. Emitted by: ERROR, EXIT.
errorType
String
The error type that the user encountered. Emitted by: ERROR, EXIT.
exitStatus
String
The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT.
institutionId
String
The ID of the selected institution. Emitted by: all events.
institutionName
String
The name of the selected institution. Emitted by: all events.
institutionSearchQuery
String
The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.
isUpdateMode
String
Indicates if the current Link session is an update mode session. Emitted by: OPEN.
matchReason
nullablestring
The reason this institution was matched, which will be either returning_user or routing_number. Emitted by: MATCHED_SELECT_INSTITUTION.
routingNumber
Optional<String>
The routing number submitted by user at the micro-deposits routing number pane. Emitted by SUBMIT_ROUTING_NUMBER.
linkSessionId
String
The link_session_id is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: all events.
mfaType
String
If set, the user has encountered one of the following MFA types: code device questions selections. Emitted by: SUBMIT_MFA and TRANSITION_VIEW when view_name is MFA.
requestId
String
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
selection
String
Either the verification method for a matched institution selected by the user or the Auth Type Select flow type selected by the user. If selection is used to describe selected verification method, then possible values are phoneotp or password; if selection is used to describe the selected Auth Type Select flow, then possible values are flow_type_manual or flow_type_instant. Emitted by: MATCHED_SELECT_VERIFY_METHOD and SELECT_AUTH_TYPE.
timestamp
String
An ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z. Emitted by: all events.
viewName
String
The name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW.
ACCEPT_TOS
The view showing Terms of Service in the identity verification flow.
CONNECTED
The user has connected their account.
CONSENT
We ask the user to consent to the privacy policy.
CREDENTIAL
Asking the user for their account credentials.
DATA_TRANSPARENCY
We disclose the data types being shared.
DATA_TRANSPARENCY_CONSENT
We ask the user to consent to the privacy policy and disclose data types being shared.
DOCUMENTARY_VERIFICATION
The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor).
ERROR
An error has occurred.
EXIT
Confirming if the user wishes to close Link.
KYC_CHECK
The view representing the "know your customer" step in the identity verification flow.
LOADING
Link is making a request to our servers.
MATCHED_CONSENT
We ask the matched user to consent to the privacy policy and SMS terms.
MATCHED_CREDENTIAL
We ask the matched user for their account credentials to a matched institution.
MATCHED_MFA
We ask the matched user for MFA authentication to verify their identity.
MFA
The user is asked by the institution for additional MFA authentication.
NUMBERS
The user is asked to insert their account and routing numbers.
OAUTH
The user is informed they will authenticate with the financial institution via OAuth.
RECAPTCHA
The user was presented with a Google reCAPTCHA to verify they are human.
RISK_CHECK
The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor).
SCREENING
The watchlist screening step in the identity verification flow.
SELECT_ACCOUNT
We ask the user to choose an account.
SELECT_AUTH_TYPE
The user is asked to choose whether to Link instantly or manually (i.e., with micro-deposits).
SELECT_BRAND
The user is asked to select a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.
SELECT_INSTITUTION
We ask the user to choose their institution.
SELFIE_CHECK
The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.
UPLOAD_DOCUMENTS
The user is asked to upload documents (for Income verification).
VERIFY_SMS
The SMS verification step in the identity verification flow.
metadataJson
nullableString
The data directly returned from the server with no client side changes.
Select Language
1class MainActivity : AppCompatActivity() {
2
3  override fun onCreate(savedInstanceState: Bundle?) {
4
5    Plaid.setLinkEventListener(linkEventListener = {
6      Log.i("Event", it.toString())
7    })
8  }
9}

Plaid Link for React Native

This section provides instructions for maintaining Plaid integrations using the deprecated public_key parameter. These instructions cannot be used for new integrations or for adding OAuth support to existing integrations. For up-to-date content on this topic, see the Link React Native SDK instead. For instructions on updating an existing legacy integration, see the Link token migration guide.

To get started with Plaid Link for React Native youʼll want to sign up for free API keys through the Plaid Developer Dashboard.

Requirements

A new version of the React Native SDK will be released around the 20th of every month. You should keep your version up-to-date to provide the best Plaid Link experience in your application.

Version Compatibility
React Native SDKAndroid SDKiOS SDKStatus
7.x.x3.2.x>=2.0.7Active
6.x.x3.x.x>=2.0.1Active
5.x.x2.1.x>=1.1.34Active
4.x.x2.0.x<=1.1.33Active
3.x.x1.x.x<=1.1.33Deprecated
2.x.x0.3.x<=1.1.27Deprecated
1.x.x< 0.3.x<=1.1.24Deprecated

Getting Started

Installing the SDK

In your react-native project directory, run:

1npm install --save react-native-plaid-link-sdk

Next Steps

PlaidLink

PlaidLink is the the React component used to open Link from a React Native application. PlaidLink renders a Pressable component, which wraps the component you provide and intercepts onPress events to open Link.

plaidLink_legacy
onSuccess
LinkSuccessListener
A function that is called when a user successfully links an Item. The function should expect one argument.
publicKeyConfig
deprecatedLinkPublicKeyConfiguration
A configuration used to open Link with a a public key
publicKey
String
The public_key associated with your account; available from the Dashboard.
oauthConfiguration
Values used to configure the application for OAuth
oauthNonce
string
An oauthNonce is required to support OAuth authentication flows when launching or re-launching Link on a mobile device and using one or more European country codes. The nonce must be at least 16 characters long.
oauthRedirectUri
An oauthRedirectUri is required to support OAuth authentication flows when launching Link on a mobile device and using one or more European country codes. Note that any redirect URI must also be added to the Allowed redirect URIs list in the developer dashboard.
clientName
string
Displayed once a user has successfully linked their Item.
countryCodes
Array<string>
Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard. Note that if you initialize with a European country code, your users will see the European consent panel during the Link flow. Supported country codes are: US, CA, ES, FR, GB, IE, NL. If not specified, will default to ['US']. If Link is launched with multiple countryCodes, only products that you are enabled for in all countries will be used by Link.
If a Link customization is being used, the countries configured here should match those in the customization.
environment
PlaidEnvironment
The Plaid API environment on which to create user accounts. Possible values are sandbox, development, and production.
product
Array<PlaidProduct>
A list of Plaid products you wish to use. Valid products are: transactions, auth, identity, assets, investments, liabilities, and payment_initiation. Example: ['auth', 'transactions']. balance is not a valid value, the Balance product does not require explicit initialization and will automatically be initialized when any other product is initialized. Only institutions that support all requested products will be shown in Link.
In Production, you will be billed for each product that you specify when initializing Link. Note that a product cannot be removed from an Item once the Item has been initialized with that product. To stop billing on an Item for subscription-based products, such as Liabilities, Investments, and Transactions, remove the Item via /item/remove.
accountSubtypes
Array<LinkAccountSubtype>
By default, Link will only display account types that are compatible with all products supplied in the product parameter. You can further limit the accounts shown in Link by using accountSubtypes to specify the account subtypes to be shown in Link. Only the specified subtypes will be shown. To indicate that all subtypes should be shown, use the value "all". If the accountSubtypes filter is used, any account type for which a filter is not specified will be entirely omitted from Link.
Example value:
{
"depository": ["checking", "savings"],
"credit": ["all"]
}
For a full list of valid types and subtypes, see the Account schema.
For institutions using OAuth, the filter will not affect the list of institutions shown by the bank in the OAuth window.
linkCustomizationName
string
Specify the name of a Link customization created in the Dashboard. The default customization is used if none is provided. When using a Link customization, the language in the customization must match the language configured via the language parameter.
token
string
Specify a link_token to authenticate your app with Link. This is a short lived, one-time use token that should be unique for each Link session. In addition to the primary flow, a link_token can be configured to launch Link in update mode. See the /link/token/create endpoint for a full list of configurations.
userLegalName
string
The end user's legal name
userPhoneNumber
string
The end user's phone number
userEmailAddress
string
The end user's email address
webhook
string
Specify a webhook to associate with an Item. Plaid fires a webhook when the Item requires updated credentials, when new data is available, or when Auth numbers have been successfully verified.
logLevel
LinkLogLevel
Set the level at which to log statements

Possible values: DEBUG, INFO, WARN, ERROR
extraParams
Record<string, any>
You do not need to use this field unless specifically instructed to by Plaid.
onExit
LinkExitListener
A function that is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The function should expect one argument.
children
React.ReactNode
The underlying component to render
1<PlaidLink
2  publicKeyConfig={{
3    clientName: 'Client Name',
4    publicKey: '<INSERT PUBLIC KEY>',
5    environment: PlaidEnvironment.SANDBOX,
6    products: Array.of(PlaidProduct.AUTH),
7    language: 'en',
8    countryCodes: Array.of('US'),
9    logLevel: LinkLogLevel.DEBUG,
10    oauthConfiguration: {
11      nonce: '',
12      redirectUri: 'https://myapp.example.com',
13    },
14  }}
15  onSuccess={(success: LinkSuccess) => {
16    console.log(success);
17  }}
18  onExit={(exit: LinkExit) => {
19    console.log(exit);
20  }}
21>
22  <Text>Add Account</Text>
23</PlaidLink>

onSuccess

The onSuccess callback returns a LinkSuccess object.

The method is called when a user successfully links an Item. The onSuccess handler returns a LinkConnection class that includes the public_token, and additional Link metadata in the form of a LinkConnectionMetadata class.

onSuccess
publicToken
String
Displayed once a user has successfully linked their Item.
metadata
LinkSuccessMetadata
Displayed once a user has successfully linked their Item.
accounts
Array<LinkAccount>
A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, accounts will only include selected accounts.
id
string
The Plaid account_id
name
nullablestring
The official account name
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, it may also not match the mask that the bank displays to the user.
type
LinkAccountType
The account type. See the Account schema for a full list of possible values
subtype
LinkAccountSubtype
The account subtype. See the Account schema for a full list of possible values
verification_status
nullableLinkAccountVerificationStatus
Indicates an Item's micro-deposit-based verification status.
pending_automatic_verification
The Item is pending automatic verification
pending_manual_verification
The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the two amounts.
automatically_verified
The Item has successfully been automatically verified
manually_verified
The Item has successfully been manually verified
verification_expired
Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed
The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.
null
The Item is not using micro-deposit verification.
institution
nullableobject
An institution object. If the Item was created via Same-Day micro-deposit verification, will be null.
name
string
The full institution name, such as 'Wells Fargo'
id
string
The Plaid institution identifier
linkSessionId
nullableString
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
metadataJson
nullableMap
The data directly returned from the server with no client side changes.
1const onSuccess = (success: LinkSuccess) => {
2  fetch('https://yourserver.com/get_access_token', {
3    method: 'POST',
4    body: {
5      publicToken: linkSuccess.publicToken,
6      accounts: linkSuccess.metadata.accounts,
7      institution: linkSuccess.metadata.institution,
8      linkSessionId: linkSuccess.metadata.linkSessionId,
9    },
10  });
11};

onExit

The onExit handler is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The PlaidError returned from the onExit handler is meant to help you guide your users after they have exited Link. We recommend storing the error and metadata information server-side in a way that can be associated with the user. You’ll also need to include this and any other relevant info in Plaid Support requests for the user.

onExit
error
LinkError
An object that contains the error type, error code, and error message of the error that was last encountered by the user. If no error was encountered, error will be null.
displayMessage
nullableString
A user-friendly representation of the error code. null if the error is not related to user action. This may change over time and is not safe for programmatic use.
errorCode
LinkErrorCode
The particular error code. Each errorType has a specific set of errorCodes. A code of 499 indicates a client-side exception.
errorType
LinkErrorType
A broad categorization of the error.
errorMessage
String
A developer-friendly representation of the error code.
errorJson
nullableString
The data directly returned from the server with no client side changes.
metadata
Map<String, Object>
An object containing information about the exit event
linkSessionId
nullableString
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
institution
nullableLinkInstitution
An institution object. If the Item was created via Same-Day micro-deposit verification, will be null.
name
string
The full institution name, such as 'Wells Fargo'
id
string
The Plaid institution identifier
status
nullableLinkExitMetadataStatus
The point at which the user exited the Link flow. One of the following values
requires_questions
User prompted to answer security questions
requires_selections
User prompted to answer multiple choice question(s)
requires_recaptcha
User prompted to solve a reCAPTCHA challenge
requires_code
User prompted to provide a one-time passcode
choose_device
User prompted to select a device on which to receive a one-time passcode
requires_credentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution
requires_account_selection
User prompted to select one or more financial accounts to share
requires_oauth
User prompted to enter an OAuth flow
institution_not_found
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
unknown
An exit status that is not handled by the current version of the SDK
requestId
nullableString
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation
metadataJson
nullableMap
The data directly returned from the server with no client side changes.
1const onExit = (linkExit: LinkExit) => {
2  supportHandler.report({
3    error: linkExit.error,
4    institution: linkExit.metadata.institution,
5    linkSessionId: linkExit.metadata.linkSessionId,
6    requestId: linkExitlinkExit.metadata.requestId,
7    status: linkExit.metadata.status,
8  });
9};

onEvent

The React Native Plaid module emits onEvent events throughout the account linking process. To receive these events use the usePlaidEmitter hook.

The onEvent callback is called at certain points in the Link flow. Unlike the handlers for onSuccess and onExit, the onEvent handler is initialized as a global lambda passed to the Plaid class. OPEN events will be sent immediately upon Link’s opening, and remaining events will be sent by the time onSuccess or onExit is called. If you need the exact time when an event happened, use the timestamp property.
The following onEvent callbacks are stable, which means that they will not be deprecated or changed: OPEN, EXIT, HANDOFF, SELECT_INSTITUTION, ERROR, BANK_INCOME_INSIGHTS_COMPLETED, IDENTITY_VERIFICATION_PASS_SESSION, IDENTITY_VERIFICATION_FAIL_SESSION. The remaining callback events are informational and subject to change.

onEvent
eventName
LinkEventName
A string representing the event that has just occurred in the Link flow.
BANK_INCOME_INSIGHTS_COMPLETED
The user has completed the Assets and Bank Income Insights flow.
CLOSE_OAUTH
The user closed the third-party website or mobile app without completing the OAuth flow.
ERROR
A recoverable error occurred in the Link flow, see the error_code metadata.
EXIT
The user has exited without completing the Link flow and the onExit callback is fired.
FAIL_OAUTH
The user encountered an error while completing the third-party's OAuth login flow.
HANDOFF
The user has exited Link after successfully linking an Item.
IDENTITY_VERIFICATION_START_STEP
The user has started a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_PASS_STEP
The user has passed a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_FAIL_STEP
The user has failed a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_PENDING_REVIEW_STEP
The user has reached the pending review state.
IDENTITY_VERIFICATION_CREATE_SESSION
The user has started a new Identity Verification session.
IDENTITY_VERIFICATION_RESUME_SESSION
The user has resumed an existing Identity Verification session.
IDENTITY_VERIFICATION_PASS_SESSION
The user has successfully completed their Identity Verification session.
IDENTITY_VERIFICATION_PENDING_REVIEW_SESSION
The user has completed their Identity Verification session, which is now in a pending review state.
IDENTITY_VERIFICATION_FAIL_SESSION
The user has failed their Identity Verification session.
IDENTITY_VERIFICATION_OPEN_UI
The user has opened the UI of their Identity Verification session.
IDENTITY_VERIFICATION_RESUME_UI
The user has resumed the UI of their Identity Verification session.
IDENTITY_VERIFICATION_CLOSE_UI
The user has closed the UI of their Identity Verification session.
MATCHED_SELECT_INSTITUTION
The user selected an institution that was presented as a matched institution. This event can be emitted either during the Returning User Experience flow or if the institution's routing_number was provided when calling /link/token/create. To distinguish between the two scenarios, see metadata.matchReason.
MATCHED_SELECT_VERIFY_METHOD
The user selected a verification method for a matched institution. This event is emitted only during the Returning User Experience flow.
OPEN
The user has opened Link.
OPEN_MY_PLAID
The user has opened my.plaid.com. This event is only sent when Link is initialized with Assets as a product.
OPEN_OAUTH
The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.
SEARCH_INSTITUTION
The user has searched for an institution.
SELECT_BRAND
The user selected a brand, e.g. Bank of America. The SELECT_BRAND event is only emitted for large financial institutions with multiple online banking portals.
SELECT_DEGRADED_INSTITUTION
The user selected an institution with a DEGRADED health status and was shown a corresponding message.
SELECT_DOWN_INSTITUTION
The user selected an institution with a DOWN health status and was shown a corresponding message.
SELECT_INSTITUTION
The user selected an institution.
SUBMIT_ACCOUNT_NUMBER
The user has submitted an account number. This event emits the account_number_mask metadata to indicate the mask of the account number the user provided.
SUBMIT_CREDENTIALS
The user has submitted credentials.
SUBMIT_MFA
The user has submitted MFA.
SUBMIT_ROUTING_NUMBER
The user has submitted routing number. This event emits the routing_number metadata to indicate user's routing number.
TRANSITION_VIEW
The TRANSITION_VIEW event indicates that the user has moved from one view to the next.
VIEW_DATA_TYPES
The user has viewed data types on the data transparency consent pane.
UNKNOWN
The UNKNOWN event indicates that the event is not handled by the current version of the SDK.
metadata
LinkEventMetadata
An object containing information about the event.
submitAccountNumber
String
The account number mask extracted from the user-provided account number. If the user-inputted account number is four digits long, account_number_mask is empty. Emitted by SUBMIT_ACCOUNT_NUMBER.
errorCode
String
The error code that the user encountered. Emitted by: ERROR, EXIT.
errorMessage
String
The error message that the user encountered. Emitted by: ERROR, EXIT.
errorType
String
The error type that the user encountered. Emitted by: ERROR, EXIT.
exitStatus
String
The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT.
institutionId
String
The ID of the selected institution. Emitted by: all events.
institutionName
String
The name of the selected institution. Emitted by: all events.
institutionSearchQuery
String
The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.
isUpdateMode
String
Indicates if the current Link session is an update mode session. Emitted by: OPEN.
matchReason
nullablestring
The reason this institution was matched, which will be either returning_user or routing_number. Emitted by: MATCHED_SELECT_INSTITUTION.
routingNumber
Optional<String>
The routing number submitted by user at the micro-deposits routing number pane. Emitted by SUBMIT_ROUTING_NUMBER.
linkSessionId
String
The linkSessionId is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: all events.
mfaType
String
If set, the user has encountered one of the following MFA types: code device questions selections. Emitted by: SUBMIT_MFA and TRANSITION_VIEW when view_name is MFA.
requestId
String
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
selection
String
Either the verification method for a matched institution selected by the user or the Auth Type Select flow type selected by the user. If selection is used to describe selected verification method, then possible values are phoneotp or password; if selection is used to describe the selected Auth Type Select flow, then possible values are flow_type_manual or flow_type_instant. Emitted by: MATCHED_SELECT_VERIFY_METHOD and SELECT_AUTH_TYPE.
timestamp
String
An ISO 8601 representation of when the event occurred. For example, 2017-09-14T14:42:19.350Z. Emitted by: all events.
viewName
LinkEventViewName
The name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW.
ACCEPT_TOS
The view showing Terms of Service in the identity verification flow.
CONNECTED
The user has connected their account.
CONSENT
We ask the user to consent to the privacy policy.
CREDENTIAL
Asking the user for their account credentials.
DATA_TRANSPARENCY
We disclose the data types being shared.
DATA_TRANSPARENCY_CONSENT
We ask the user to consent to the privacy policy and disclose data types being shared.
DOCUMENTARY_VERIFICATION
The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor).
ERROR
An error has occurred.
EXIT
Confirming if the user wishes to close Link.
KYC_CHECK
The view representing the "know your customer" step in the identity verification flow.
LOADING
Link is making a request to our servers.
MATCHED_CONSENT
We ask the matched user to consent to the privacy policy and SMS terms.
MATCHED_CREDENTIAL
We ask the matched user for their account credentials to a matched institution.
MATCHED_MFA
We ask the matched user for MFA authentication to verify their identity.
MFA
The user is asked by the institution for additional MFA authentication.
NUMBERS
The user is asked to insert their account and routing numbers.
OAUTH
The user is informed they will authenticate with the financial institution via OAuth.
RECAPTCHA
The user was presented with a Google reCAPTCHA to verify they are human.
RISK_CHECK
The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor).
SCREENING
The watchlist screening step in the identity verification flow.
SELECT_ACCOUNT
We ask the user to choose an account.
SELECT_AUTH_TYPE
The user is asked to choose whether to Link instantly or manually (i.e., with micro-deposits).
SELECT_BRAND
The user is asked to select a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.
SELECT_INSTITUTION
We ask the user to choose their institution.
SELFIE_CHECK
The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.
UPLOAD_DOCUMENTS
The user is asked to upload documents (for Income verification).
VERIFY_SMS
The SMS verification step in the identity verification flow.
1usePlaidEmitter((event: LinkEvent) => {
2  console.log(event);
3});

OAuth

Using Plaid Link with an OAuth flow requires some additional setup instructions. For details, see the OAuth guide.

Upgrading

Plaid Link for Webviews

This section provides instructions for maintaining Plaid integrations using the deprecated public_key parameter. These instructions cannot be used for new integrations or for adding OAuth support to existing integrations. For up-to-date content on this topic, see the Link Webview SDK instead. For instructions on updating an existing legacy integration, see the Link token migration guide.

Here you will find instructions on how to integrate and use Plaid Link inside a Webview. We recommend starting with one of our sample Webview apps:

Each example app is runnable (on both simulators and devices) and includes code to initialize Link and process events sent from Link to your app via HTTP redirects.

Installation

Link is optimized to work within Webviews, including on iOS and Android. The Link initialization URL to use for Webviews is:

1https://cdn.plaid.com/link/v2/stable/link.html

The Link configuration options for a Webview integration are passed via querystring rather than via a client-side JavaScript call. See the create section below for details on the available initialization parameters.

Communication between Link and your app

Communication between the Webview and your app is handled by HTTP redirects rather than client-side JavaScript callbacks. These redirects should be intercepted by your app. The example apps include sample code to do this.

All redirect URLs have the scheme plaidlink. The event type is communicated via the URL host and data is passed via the querystring.

1plaidlink://

There are three supported events, connected, exit, and event, which are documented below.

Create

create_legacy
isWebview
boolean
Set to true, to trigger the Webview integration.
clientName
string
Displayed once a user has successfully linked their Item.
env
string
The Plaid API environment on which to create user accounts. Possible values are development, sandbox, respectively. For Production use, use production.
key
string
The public_key associated with your account; available from the Dashboard.
product
string
A list of Plaid products you wish to use. Valid products are: transactions, auth, identity, assets, investments, liabilities, and payment_initiation. Example: auth,transactions. balance is not a valid value, the Balance product does not require explicit initialization and will automatically be initialized when any other product is initialized. Only institutions that support all requested products will be shown in Link.
In Production, you will be billed for each product that you specify when initializing Link. Note that a product cannot be removed from an Item once the Item has been initialized with that product. To stop billing on an Item for subscription-based products, such as Liabilities, Investments, and Transactions, remove the Item via /item/remove.
language
string
Specify a Plaid-supported language to localize Link. English will be used by default. Supported languages:
  • English (en)
  • French (fr)
  • Spanish (es)
  • Dutch (nl)
When using a Link customization, language must be set to match the language used in the customization.
countryCodes
string
Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard. Note that if you initialize with a European country code, your users will see the European consent panel during the Link flow. Supported country codes are: US, CA, ES, FR, GB, IE, NL. If not specified, will default to ['US']. If Link is launched with multiple countryCodes, only products that you are enabled for in all countries will be used by Link.
If a Link customization is being used, the countries configured here should match those in the customization.
To use the Auth features Instant Match, Automated Micro-deposits, or Same-day Micro-deposits, countryCodes must be set to ['US'].
accountSubtypes
object
By default, Link will only display account types that are compatible with all products supplied in the product parameter. You can further limit the accounts shown in Link by using accountSubtypes to specify the account subtypes to be shown in Link. Only the specified subtypes will be shown. To indicate that all subtypes should be shown, use the value "all". If the accountSubtypes filter is used, any account type for which a filter is not specified will be entirely omitted from Link.
Example value:
{
"depository": ["checking", "savings"],
"credit": ["all"]
}
For a full list of valid types and subtypes, see the Account schema.
For institutions using OAuth, the filter will not affect the list of institutions shown by the bank in the OAuth window.
<accountType>: [accountSubtype]
string
An object of accountTypes composed of an array of accountSubtypes to filter
webhook
string
Specify a webhook to associate with an Item. Plaid fires a webhook when the Item requires updated credentials, when new data is available, or when Auth numbers have been successfully verified.
linkCustomizationName
string
Specify the name of a Link customization created in the Dashboard. The default customization is used if none is provided. When using a Link customization, the language in the customization must match the language configured via the language parameter.
token
string
Specify a public_token to launch Link in update mode for a particular Item. This will cause Link to open directly to the authentication step for that Item's institution. Use the /item/public_token/create endpoint to generate a public_token for an Item.
oauthNonce
string
An oauthNonce is required to support OAuth authentication flows when launching or re-launching Link on a mobile device and using one or more European country codes. The nonce must be at least 16 characters long.
oauthRedirectUri
string
An oauthRedirectUri is required to support OAuth authentication flows when launching Link on a mobile device and using one or more European country codes.
oauthStateId
string
An oauthStateId is required to support OAuth authentication flows when re-launching Link on a mobile device and using one or more European country codes.
paymentToken
string
A paymentToken must be specified if you are using the Payment Initiation (UK and Europe) product. This will cause Link to open directly to the Payment Initiation flow. Use the /payment_initiation/payment/token/create endpoint to generate a payment_token.
1https://cdn.plaid.com/link/v2/stable/link.html
2  ?isWebview=true
3  &clientName=Your%20App
4  &env=sandbox
5  &key=PUBLIC_KEY
6  &product=transactions,auth
7  &language=en
8  &countryCodes=US,CA
9  &webhook=https%3A%2F%2Fyourappurl.com
10  &linkCustomizationName=default
11  &token=
12  &paymentToken=
13  &oauthNonce=
14  &oauthRedirectUri=
15  &oauthStateId=

connected

The connected event is analogous to the onSuccess callback in Link Web and is sent when a user successfully links an Item. The following information is available from the querystring event:

connected
public_token
string
Displayed once a user has successfully linked their Item.
institution_name
string
The full institution name, such as 'Wells Fargo'
institution_id
string
The Plaid institution identifier
accounts
object
A JSON-stringified representation of the account(s) attached to the connected Item. If Account Select is enabled via the developer dashboard, accounts will only include selected accounts.
_id
string
The Plaid account_id
meta
object
The account metadata
name
string
The official account name
number
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, it may also not match the mask that the bank displays to the user.
type
string
The account type. See the Account schema for a full list of possible values
subtype
string
The account subtype. See the Account schema for a full list of possible values
verification_status
string
When all Auth features are enabled by initializing Link with the user object, the accounts object includes an Item's verification_status. See Auth accounts for a full list of possible values.
class_type
nullablestring
If micro-deposit verification is being used, indicates whether the account being verified is a business or personal account.
transfer_status
nullablestring
The status of a transfer. Returned only when Transfer UI is implemented.
  • COMPLETE – The transfer was completed.
  • INCOMPLETE – The transfer could not be completed. For help, see Troubleshooting transfers.


Possible values: COMPLETE, INCOMPLETE
link_session_id
string
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
1plaidlink://connected
2  ?public_token=public-sandbox-fb7cca4a-82e6-4707
3  &institution_id=ins_3
4  &institution_name=Chase
5  &accounts='[{"name":"Plaid Savings","id":"QPO8Jo8vdDHMepg41PBwckXm4KdK1yUdmXOwK", "mask": "0000", "type": "depository", "subtype": "checking"}]'
6  &link_session_id=79e772be-547d-4c9c-8b76-4ac4ed4c441a
1accounts= [
2  {
3    id: 'ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy',
4    name: 'Plaid Checking',
5    mask: '0000',
6    type: 'depository',
7    subtype: 'checking',
8    verification_status: ''
9  },
10  {
11    id: '9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4',
12    name: 'Plaid Saving',
13    mask: '1111',
14    type: 'depository',
15    subtype: 'savings'
16  }
17  ...
18]

exit

The exit event is analogous to the onExit callback and is sent when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. Note that on Android devices, an exit event will not be sent if the user exits Link through a system action, such as hitting the browser back button. The following information is available from the querystring:

exit
status
string
The point at which the user exited the Link flow. One of the following values.
requires_questions
User prompted to answer security questions
requires_selections
User prompted to answer multiple choice question(s)
requires_code
User prompted to provide a one-time passcode
choose_device
User prompted to select a device on which to receive a one-time passcode
requires_credentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution
requires_account_selection
User prompted to select one or more financial accounts to share
requires_oauth
User prompted to enter an OAuth flow
institution_not_found
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
error_type
String
A broad categorization of the error.
error_code
String
The particular error code. Each error_type has a specific set of error_codes.
error_message
String
A developer-friendly representation of the error code.
display_message
nullableString
A user-friendly representation of the error code. null if the error is not related to user action. This may change over time and is not safe for programmatic use.
institution_name
string
The full institution name, such as Wells Fargo
institution_id
string
The Plaid institution identifier
link_session_id
string
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
request_id
string
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation.
1plaidlink://exit
2  ?status=requires_credentials
3  &error_type=ITEM_ERROR
4  &error_code=ITEM_LOGIN_REQUIRED
5  &error_display_message=The%20credentials%20were%20not%20correct.%20Please%20try%20again.
6  &error_message=the%20credentials%20were%20not%20correct
7  &institution_id=ins_3
8  &institution_name=Chase
9  &link_session_id=79e772be-547d-4c9c-8b76-4ac4ed4c441a
10  &request_id=m8MDnv9okwxFNBV

event

The event message is analogous to the Link Web onEvent callback and is called as the user moves through the Link flow. The querystring will always contain all possible keys, though not all keys will have values. The event_name will dictate which keys are populated.

event
event_name
string
A string representing the event that has just occurred in the Link flow.
BANK_INCOME_INSIGHTS_COMPLETED
The user has completed the Assets and Bank Income Insights flow.
CLOSE_OAUTH
The user closed the third-party website or mobile app without completing the OAuth flow.
ERROR
A recoverable error occurred in the Link flow, see the error_code metadata.
EXIT
The user has exited without completing the Link flow and the exit callback is fired.
FAIL_OAUTH
The user encountered an error while completing the third-party's OAuth login flow.
HANDOFF
The user has exited Link after successfully linking an Item.
MATCHED_SELECT_INSTITUTION
The user selected an institution that was presented as a matched institution. This event can be emitted either during the Returning User Experience flow or if the institution's routing_number was provided when calling /link/token/create. To distinguish between the two scenarios, see metadata.match_reason.
MATCHED_SELECT_VERIFY_METHOD
The user selected a verification method for a matched institution. This event is emitted only during the Returning User Experience flow.
OPEN
The user has opened Link.
OPEN_MY_PLAID
The user has opened my.plaid.com. This event is only sent when Link is initialized with Assets as a product
OPEN_OAUTH
The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.
SEARCH_INSTITUTION
The user has searched for an institution.
SELECT_BRAND
The user selected a brand, e.g. Bank of America. The SELECT_BRAND event is only emitted for large financial institutions with multiple online banking portals.
SELECT_DEGRADED_INSTITUTION
The user selected an institution with a DEGRADED health status and was shown a corresponding message.
SELECT_DOWN_INSTITUTION
The user selected an institution with a DOWN health status and was shown a corresponding message.
SELECT_INSTITUTION
The user selected an institution.
SUBMIT_ACCOUNT_NUMBER
The user has submitted an account number. This event emits the account_number_mask metadata to indicate the mask of the account number the user provided.
SUBMIT_CREDENTIALS
The user has submitted credentials.
SUBMIT_DOCUMENTS
The user is being prompted to submit documents for an Income verification flow.
SUBMIT_DOCUMENTS_ERROR
The user encountered an error when submitting documents for an Income verification flow.
SUBMIT_DOCUMENTS_SUCCESS
The user has successfully submitted documents for an Income verification flow.
SUBMIT_MFA
The user has submitted MFA.
SUBMIT_ROUTING_NUMBER
The user has submitted routing number. This event emits the routing_number metadata to indicate user's routing number.
TRANSITION_VIEW
The TRANSITION_VIEW event indicates that the user has moved from one view to the next.
VIEW_DATA_TYPES
The user has viewed data types on the data transparency consent pane.
error_type
nullablestring
The error type that the user encountered. Emitted by: ERROR, EXIT.
error_code
nullablestring
The error code that the user encountered. Emitted by ERROR, EXIT.
error_message
nullablestring
The error message that the user encountered. Emitted by: ERROR, EXIT.
exit_status
nullablestring
The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT
institution_id
nullablestring
The ID of the selected institution. Emitted by: all events.
institution_name
nullablestring
The name of the selected institution. Emitted by: all events.
institution_search_query
nullablestring
The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.
is_update_mode
nullablestring
Indicates if the current Link session is an update mode session. Emitted by: OPEN.
match_reason
nullablestring
The reason this institution was matched, which will be either returning_user or routing_number. Emitted by: MATCHED_SELECT_INSTITUTION
mfa_type
nullablestring
If set, the user has encountered one of the following MFA types: code, device, questions, selections. Emitted by: SUBMIT_MFA and TRANSITION_VIEW when view_name is MFA
view_name
nullablestring
The name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW.
ACCEPT_TOS
The view showing Terms of Service in the identity verification flow.
CONNECTED
The user has connected their account.
CONSENT
We ask the user to consent to the privacy policy.
CREDENTIAL
Asking the user for their account credentials.
DATA_TRANSPARENCY
We disclose the data types being shared.
DATA_TRANSPARENCY_CONSENT
We ask the user to consent to the privacy policy and disclose data types being shared.
DOCUMENTARY_VERIFICATION
The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor).
ERROR
An error has occurred.
EXIT
Confirming if the user wishes to close Link.
KYC_CHECK
The view representing the "know your customer" step in the identity verification flow.
LOADING
Link is making a request to our servers.
MATCHED_CONSENT
We ask the matched user to consent to the privacy policy and SMS terms.
MATCHED_CREDENTIAL
We ask the matched user for their account credentials to a matched institution.
MATCHED_MFA
We ask the matched user for MFA authentication to verify their identity.
MFA
The user is asked by the institution for additional MFA authentication.
NUMBERS
The user is asked to insert their account and routing numbers.
OAUTH
The user is informed they will authenticate with the financial institution via OAuth.
RECAPTCHA
The user was presented with a Google reCAPTCHA to verify they are human.
RISK_CHECK
The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor).
SCREENING
The watchlist screening step in the identity verification flow.
SELECT_ACCOUNT
We ask the user to choose an account.
SELECT_BRAND
The user selected a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.
SELECT_INSTITUTION
We ask the user to choose their institution.
SELFIE_CHECK
The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.
VERIFY_SMS
The SMS verification step in the identity verification flow.
request_id
string
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
link_session_id
string
The link_session_id is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: all events.
timestamp
string
An ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z. Emitted by: all events.
selection
nullablestring
Either the verification method for a matched institution selected by the user or the Flexible Auth flow type selected by the user. If selection is used to describe selected verification method, then possible values are phoneotp or password; if selection is used to describe the selected Flexible Auth flow, then possible values are flow_type_manual or flow_type_instant. Emitted by: MATCHED_SELECT_VERIFY_METHOD and SELECT_AUTH_TYPE.
1plaidlink://event
2  &event_name=SELECT_INSTITUTION
3  ?error_type=ITEM_ERROR
4  &error_code=ITEM_LOGIN_REQUIRED
5  &error_message=the%20credentials%20were%20not%20correct
6  &exit_status
7  &institution_id=ins_55
8  &institution_name=HSBC
9  &institution_search_query=h
10  &mfa_type
11  &view_name=ERROR
12  &request_id
13  &link_session_id=821f45a8-854a-4dbb-8e5f-73f75350e7e7
14  &timestamp=2018-10-05T15%3A22%3A50.542Z

Update mode

When to use update mode

Over time, Items may need to refresh authentication information. This can happen if the user changes a password, if MFA requirements change, or if the login becomes locked. An Item can also require its authentication refreshed if it was only authorized for a limited amount of time and that authorization has expired or is about to expire. This can commonly happen to Items from European institutions that comply with the PSD2 regulation, which mandates that access to an Item can only be granted for 90 days at a time before it must be refreshed. Receiving an ITEM_LOGIN_REQUIRED error or a PENDING_EXPIRATION webhook indicates that the Item should be re-initialized via update mode.

Using update mode

To use update mode for an Item, initialize Link with a public_token for the Item that you wish to update. You can obtain the public_token using the /item/public_token/create endpoint:

Select Language
1// Create a one-time use public_token for the Item.
2// This public_token can be used to initialize Link
3// in update mode for the user
4app.get('/create_public_token', function(request, response, next) {
5  client.createPublicToken(ACCESS_TOKEN, function(err, res) {
6    if(error != null) {
7      console.log(msg + "\n" + JSON.stringify(err));
8      response.json({error: JSON.stringify(err)}):
9    } else {
10      // Use the public_token to initialize Link
11      var PUBLIC_TOKEN = res.public_token;
12      response.json({public_token: PUBLIC_TOKEN});
13    }
14  });
15});

Link auto-detects the appropriate institution and handles the credential and multi-factor authentication process, if needed.

An Item's access_token does not change when using Link in update mode, so there is no need to repeat the exchange token process.

1// Initialize Link with the token parameter
2// set to the generated public_token for the Item
3const linkHandler = Plaid.create({
4  env: 'sandbox',
5  clientName: 'Client Name',
6  key: 'PUBLIC_KEY',
7  product: ['transactions'],
8  token: 'GENERATED_PUBLIC_TOKEN',
9  onSuccess: (public_token, metadata) => {
10    // You do not need to repeat the /item/public_token/exchange
11    // process when a user uses Link in update mode.
12    // The Item's access_token has not changed.
13  },
14  onExit: (err, metadata) => {
15    // The user exited the Link flow.
16    if (err != null) {
17      // The user encountered a Plaid API error prior
18      // to exiting.
19    }
20    // metadata contains the most recent API request ID and the
21    // Link session ID. Storing this information is helpful
22    // for support.
23  },
24});

Link will automatically detect the institution ID associated with the public_token and present the appropriate credential view to your user.

Related errors

Below is a list of errors that you may encounter in update mode or that may cause you to launch the update mode flow:

  • ITEM_LOGIN_REQUIRED – The financial institution indicated that the user's password or MFA information has changed. They will need to reauthenticate via Link's update mode.
  • INVALID_UPDATED_USERNAME – The username associated with an item is no longer valid.

OAuth Integration (Europe)

This section provides instructions for maintaining Plaid integrations using the deprecated public_key parameter. These instructions cannot be used for new integrations or for adding OAuth support to existing integrations. For instructions on updating an existing legacy integration, see the Link token migration guide.

Some European institutions use an OAuth authentication flow, in which Plaid Link redirects the end user to their bank’s website or mobile app to authenticate. If you are initializing Link with one or more European country codes, your integration may require changes in order to support OAuth authentication flows.

Integration TypeChanges Required
Desktop webNo
Mobile webYes
WebViewYes
Android SDKNo
iOS SDKYes
React Native for AndroidNo
React Native for iOSYes

If your integration requires changes, you will need to launch Link twice, once before and once after the OAuth redirect. The first time, you will need to provide two additional configuration parameters, oauthNonce and oauthRedirectUri. After the user completes the OAuth flow, Plaid will redirect back to your application via the oauthRedirectUri with a query parameter called oauth_state_id. To complete the Link flow, dismiss the first Link instance and re-initialize Link with two configuration parameters, the oauthNonce from the original Link initialization, as well as the oauthStateId from the oauth_state_id query parameter.

For security, the oauthNonce must be uniquely generated for each login and must be at least 16 characters long. We recommend using a UUID.

Before re-initializing Link, you should re-authenticate the end user to prevent a confused deputy problem. This can be accomplished by including one or more query parameters in your oauthRedirectUri. For example, you could include a parameter called user_id. Before re-initializing Link, you would check that the user_id in the redirect URI matches the user_id in your application state (e.g. a cookie).

Note that in mobile web browsers, if the end user has their bank’s mobile app installed, they will be redirected to the bank’s mobile app to authenticate, after which they will be redirected back to your web application in a new tab.

Allowed redirect URIs

To prevent open redirect attacks, your oauthRedirectUri must be configured through the developer dashboard. For security, the oauthRedirectUri cannot contain the oauthNonce.

App links

For mobile app integrations, the oauthRedirectUri must be registered as an app link to enable app-to-app authentication flows. You will need to configure an Android App Link or an Apple App Association File. Custom URI schemes are not supported; a proper universal link must be used.

Payment Initiation (UK and Europe)

This section provides instructions for maintaining Plaid integrations using the deprecated public_key parameter. These instructions cannot be used for new integrations or for adding OAuth support to existing integrations. For up-to-date content on this topic, see Payment Initiation instead. For instructions on updating an existing legacy integration, see the Link token migration guide.

The UK Payment Initiation API enables payment transfers within your app. Plaid supports both domestic payments denominated in pound sterling (typically via the Faster Payments network, although this is up to the institution) and international payments denominated in euro (typically via SEPA Credit Transfer). Each time a client wants to receive a payment, the end user must authorize the payment in Link before the payment can be initiated.

Note: The revised EU Directive on Payment Services ("PSD2") regulations require strong customer authentication ("SCA") for each payment order.

Initializing Link

To initialize Link for Payment Initiation, set payment_initiation as the only product and include the payment token. If an item has previously been created for the end user making the payment, a public_token can be included to initialize Link directly to the institution associated with the existing Item.

Creating a payment token

Create payment token

The /payment_initiation/payment/token/create endpoint has been deprecated. New Plaid customers will be unable to use this endpoint, and existing customers are encouraged to migrate to the newer, link_token-based flow. The recommended flow is to provide the payment_id to /link/token/create, which returns a link_token used to initialize Link.
The /payment_initiation/payment/token/create is used to create a payment_token, which can then be used in Link initialization to enter a payment initiation flow. You can only use a payment_token once. If this attempt fails, the end user aborts the flow, or the token expires, you will need to create a new payment token. Creating a new payment token does not require end user input.

payment_initiation/payment/token/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
payment_id
requiredstring
The payment_id returned from /payment_initiation/payment/create.
Select Language
1const response = await client.createPaymentToken(paymentID).catch((err) => {
2  // handle error
3});
4const paymentToken = response.payment_token;
5const paymentTokenExpirationTime = response.payment_token_expiration_time;
payment_initiation/payment/token/create

Response fields and example

payment_token
string
A payment_token that can be provided to Link initialization to enter the payment initiation flow
payment_token_expiration_time
string
The date and time at which the token will expire, in ISO 8601 format. A payment_token expires after 15 minutes.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "payment_token": "payment-token-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
3  "payment_token_expiration_time": "2020-01-01T00:00:00Z",
4  "request_id": "4ciYVmesrySiUAB"
5}
Was this helpful?

auth partnerships stripe

Add Stripe to your app

Use Stripe with Plaid Auth to send and receive payments


Plaid and Stripe have partnered to offer frictionless money transfers without the need to ever handle an account or routing number. Use Plaid Link to instantly authenticate your customer's account and automatically generate a Stripe bank account token so that you can accept ACH payments via their ACH Charges and Sources API.

This guide is designed for those who already have a ACH-enabled account at both Stripe and Plaid. If that's not you, Sign up for a Plaid Dashboard account, then head over to the Stripe ACH Charges and Sources docs to get a Stripe account.

Note that Stripe has marked the Charges and Sources API as deprecated. However, the Charges and Sources API and Plaid integration are still both fully supported by both Plaid and Stripe.

The sample Plaid integration code used in the Stripe-hosted ACH documentation demonstrates the use of a legacy version of the Plaid client libraries. For new customers, we recommend using the sample code within this guide for building your integration.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication.

Your customers will use Link to authenticate with their financial institution and select the depository account they wish to use for ACH transactions. From there, you'll receive a Plaid access_token, allowing you to leverage real-time balance checks and transaction data, and a Stripe bank_account_token, which allows you to move money via Stripe's ACH API without ever handling an account or routing number.

Instructions

Set up your Plaid and Stripe accounts

You'll need accounts at both Plaid and Stripe in order to use the Plaid Link + Stripe integration. You'll also need to connect your Plaid and Stripe accounts so that Plaid can facilitate the creation of bank account tokens on your behalf.

First, sign up for a Stripe account if you do not already have one and then verify that it is enabled for ACH access. To verify that your Stripe account is ACH enabled, head to the Charges and Sources ACH Guide when you are logged in to your Stripe account. If you see:

your account is not enabled. Click 'Accept Terms of Service' to enable your Stripe account for ACH. If you do not see the 'Accept Terms of Service' button, your Stripe account is already enabled for ACH access and you do not need to take any action.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one. Your account will be automatically enabled for integration access.

To verify that your Plaid account is enabled for the integration, go to the Integrations section of the account dashboard. If you see:

your Plaid account is enabled for the integration but you have not connected your Stripe account.

Click the 'Connect With Stripe' button to connect your Plaid and Stripe accounts. This step is required so that Plaid can facilitate the creation of Stripe bank account tokens on your behalf.

Once your Stripe account is connected, you'll see:

Your Plaid account is now set up for the integration!

Complete your Plaid application profile and company profile

After connecting your Stripe and Plaid accounts, you'll need to complete your Plaid application profile and company profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of parameters, see the /link/token/create reference.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Stripe bank account token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onLoad: function() {
9          // The Link module finished loading.
10      },
11      onSuccess: function(public_token, metadata) {
12        // The onSuccess function is called when the user has
13        // successfully authenticated and selected an account to
14        // use.
15        //
16        // When called, you will send the public_token
17        // and the data about which account to use
18        // to your backend app server. In this example,
19        // we assume "Account Select" is set to 
20        // "enabled for one account".
21        //
22        // sendDataToBackendServer({
23        //   public_token: public_token,
24        //   account_id: metadata.accounts[0].id
25        // });
26      },
27      onExit: function(err, metadata) {
28        // The user exited the Link flow.
29        if (err != null) {
30            // The user encountered a Plaid API error
31            // prior to exiting.
32        }
33        // metadata contains information about the institution
34        // that the user selected and the most recent
35        // API request IDs.
36        // Storing this information can be helpful for support.
37      },
38    });
39  })();
40
41  // Trigger the authentication view
42  document.getElementById('linkButton').onclick = function() {
43    linkHandler.open();
44  };
45</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. In order to avoid any confusion about which account your user wishes to use with Stripe, it is recommended to set Account Select to "enabled for one account" in the Plaid developer dashboard. When this setting is selected, the accounts array will always contain exactly one element.

Once you have identified the account you will use, you will send Plaid the account_id property of the account along with the access_token you obtained from /item/public_token/exchange. Plaid will automatically create and return a Stripe bank account token for this account, which can then be used to move money via Stripe's ACH API. The bank account token will be linked to the Stripe account you linked in your Plaid Dashboard.

Note that the Stripe bank account token is a one-time use token. To store bank account information for later use, you can use a Stripe customer object and create an associated bank account from the token, or you can use a Stripe Custom account and create an associated external bank account from the token. This bank account information should work indefinitely, unless the user's bank account information changes or they revoke Plaid's permissions to access their account (when using certain financial institutions). The Plaid access_token, on the other hand, does not expire and should be persisted securely.

Stripe bank account information cannot be modified once the bank account token has been created. If you ever need to change the bank account details used by Stripe for a specific customer, you should repeat this process from the beginning, including creating a link_token, sending the customer through the Link flow, generating a new bank account token, and creating a new customer object or Custom account.

Select group for content switcher
Select Language
1// Change sandbox to development to test with live users and change
2// to production when you're ready to go live!
3const { Configuration, PlaidApi, PlaidEnvironments, ProcessorStripeBankAccountTokenCreateRequest } = require('plaid');
4const configuration = new Configuration({
5  basePath: PlaidEnvironments[process.env.PLAID_ENV],
6  baseOptions: {
7    headers: {
8      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
9      'PLAID-SECRET': process.env.PLAID_SECRET,
10      'Plaid-Version': '2020-09-14',
11    },
12  },
13});
14
15const plaidClient = new PlaidApi(configuration);
16
17try {
18  // Exchange the public_token from Plaid Link for an access token.
19  const tokenResponse = await plaidClient.itemPublicTokenExchange({
20    public_token: publicToken,
21  });
22  const accessToken = tokenResponse.data.access_token;
23
24  // Generate a bank account token
25  const request: ProcessorStripeBankAccountTokenCreateRequest = {
26    access_token: accessToken,
27    account_id: accountID,
28  };
29  const stripeTokenResponse = await plaidClient.processorStripeBankAccountTokenCreate(
30    request,
31  );
32  const bankAccountToken = stripeTokenResponse.data.stripe_bank_account_token;
33} catch (error) {
34  // handle error
35}

For a valid request, the API will return a JSON response similar to:

1{
2  "stripe_bank_account_token": "btok_5oEetfLzPklE1fwJZ7SG",
3  "request_id": "[Unique request ID]"
4}

For possible error codes, see the full listing of Plaid error codes.

Note: The account_id parameter is required if you wish to receive a Stripe bank account token.

Test with Sandbox credentials

You can create Stripe bank account tokens in all three API environments:

Plaid's Sandbox API environment is compatible with Stripe's "test mode" API. To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials when launching Link with a link_token created in the Sandbox environment. The Stripe bank account token created in the Sandbox environment will always match the Stripe bank test account with account number 000123456789 and routing number 110000000, and with the Stripe account that is linked in the Plaid developer dashboard.

Use Stripe's ACH API in test mode to create test transfers using the bank account tokens you retrieve from Plaid's Sandbox API environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox and Development environments (https://sandbox.plaid.com and https://development.plaid.com), which allows you to test with Sandbox API credentials and up to 100 live users. To move to Production, please request access from the Dashboard.

Next steps

Once you're successfully retrieving Stripe bank_account_tokens, you're ready to make ACH transactions with Stripe. Head to Stripe's ACH guide to get started, and if you have any issues, please reach out to Stripe Support.

Example code in Plaid Pattern

For a real-life example of an app that integrates a processor partner, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. (Note that while the processor token creation call in Plaid Pattern's items.js demonstrates usage of the /processor/token/create endpoint for creating a processor token, Stripe integrations should use the /processor/stripe/bank_account_token/create endpoint instead and create a bank account token.)

Troubleshooting

Stripe bank account token not returned

When a stripe_bank_account_token is not returned, a typical cause is that your Stripe and Plaid accounts have not yet been linked. First, be sure that your Stripe account has been configured to accept ACH transfers. Then, link your Stripe account to your Plaid account and re-try your request.

Stripe::InvalidRequestError: No such token

The Stripe::InvalidRequestError: No such token error is returned by Stripe when the bank_account_token could not be used with the Stripe API. Make sure you are not mixing Plaid's Sandbox environment with Stripe's production environment and that, if you have more than one Stripe account or more than one Plaid client_id, you are using the Stripe account that is linked to the Plaid client_id you are using.

Support and questions

Find answers to many common integration questions and concerns, such as pricing, sandbox and test mode usage in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

link webview

Link Webview SDK

Reference for integrating with the Link Webview JavaScript SDK

Plaid does not recommend the use of webviews for new integrations. Plaid's SDKs for Android, iOS, and React Native provide the easiest and best way to build a mobile Plaid experience and are recommended for all developers.

Beginning September 30, 2023, all Webview-based integrations will need to extend the Webview handler for redirects in order to support Chase OAuth. This can be accomplished with code samples for iOS and Android. For more details, see Extending webview instances to support certain institutions in the OAuth Guide and the in-process Webview deprecation notice.

Overview

To integrate and use Plaid Link inside a Webview, we recommend starting with one of our sample Webview apps:

Each example app is runnable (on both simulators and devices) and includes code to initialize Link and process events sent from Link to your app via HTTP redirects.

Link webview

Installation

Link is optimized to work within Webviews, including on iOS and Android. The Link initialization URL to use for Webviews is:

1https://cdn.plaid.com/link/v2/stable/link.html

The Link configuration options for a Webview integration are passed via querystring rather than via a client-side JavaScript call. See the create section below for details on the available initialization parameters.

Communication between Link and your app

Communication between the Webview and your app is handled by HTTP redirects rather than client-side JavaScript callbacks. These redirects should be intercepted by your app. The example apps include sample code to do this.

All redirect URLs have the scheme plaidlink. The event type is communicated via the URL host and data is passed via the querystring.

1plaidlink://

There are three supported events, connected, exit, and event, which are documented below.

Create

create
isWebview
boolean
Set to true, to trigger the Webview integration.
token
string
Specify a link_token to authenticate your app with Link. This is a short lived, one-time use token that should be unique for each Link session. In addition to the primary flow, a link_token can be configured to launch Link in update mode. See the /link/token/create endpoint for a full list of configurations.
receivedRedirectUri
string
A receivedRedirectUri is required to support OAuth authentication flows when re-launching Link on a mobile device. Note that any unsafe ASCII characters in the receivedRedirectUri in the webview query string must be URL-encoded.
key
deprecatedstring
The public_key is no longer used for new implementations of Link. If your integration is still using a public_key, see the migration guide to upgrade to using a link_token. See the maintenance guide to troubleshoot any public_key issues.
1https://cdn.plaid.com/link/v2/stable/link.html
2  ?isWebview=true
3  &token="GENERATED_LINK_TOKEN"
4  &receivedRedirectUri=

connected

The connected event is analogous to the onSuccess callback in Link Web and is sent when a user successfully links an Item. The following information is available from the querystring event:

connected
public_token
string
Displayed once a user has successfully linked their Item.
institution_name
string
The full institution name, such as 'Wells Fargo'
institution_id
string
The Plaid institution identifier
accounts
object
A JSON-stringified representation of the account(s) attached to the connected Item. If Account Select is enabled via the developer dashboard, accounts will only include selected accounts.
_id
string
The Plaid account_id
meta
object
The account metadata
name
string
The official account name
number
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, it may also not match the mask that the bank displays to the user.
type
string
The account type. See the Account schema for a full list of possible values
subtype
string
The account subtype. See the Account schema for a full list of possible values
verification_status
string
When all Auth features are enabled by initializing Link with the user object, the accounts object includes an Item's verification_status. See Auth accounts for a full list of possible values.
class_type
nullablestring
If micro-deposit verification is being used, indicates whether the account being verified is a business or personal account.
transfer_status
nullablestring
The status of a transfer. Returned only when Transfer UI is implemented.
  • COMPLETE – The transfer was completed.
  • INCOMPLETE – The transfer could not be completed. For help, see Troubleshooting transfers.


Possible values: COMPLETE, INCOMPLETE
link_session_id
string
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
1plaidlink://connected
2  ?public_token=public-sandbox-fb7cca4a-82e6-4707
3  &institution_id=ins_3
4  &institution_name=Chase
5  &accounts='[{"_id":"QPO8Jo8vdDHMepg41PBwckXm4KdK1yUdmXOwK", "meta": {"name":"Plaid Savings", "number": "0000"}, "subtype": "checking", "type": "depository" }]'
6  &link_session_id=79e772be-547d-4c9c-8b76-4ac4ed4c441a
1"accounts": [
2  {
3    "_id": "ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy",
4    "meta": {
5      "name": "Plaid Checking",
6      "number": "0000",
7    },
8    "type": "depository",
9    "subtype": "checking",
10    "verification_status": ""
11  },
12  {
13    "_id": "9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4",
14    "meta": {
15      "name": "Plaid Saving",
16      "number": "1111",
17    },
18    "type": "depository",
19    "subtype": "savings"
20  }
21  ...
22]

exit

The exit event is analogous to the onExit callback and is sent when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. Note that on Android devices, an exit event will not be sent if the user exits Link through a system action, such as hitting the browser back button. The following information is available from the querystring:

exit
status
string
The point at which the user exited the Link flow. One of the following values.
requires_questions
User prompted to answer security questions
requires_selections
User prompted to answer multiple choice question(s)
requires_code
User prompted to provide a one-time passcode
choose_device
User prompted to select a device on which to receive a one-time passcode
requires_credentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution
requires_account_selection
User prompted to select one or more financial accounts to share
requires_oauth
User prompted to enter an OAuth flow
institution_not_found
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
error_type
String
A broad categorization of the error.
error_code
String
The particular error code. Each error_type has a specific set of error_codes.
error_message
String
A developer-friendly representation of the error code.
display_message
nullableString
A user-friendly representation of the error code. null if the error is not related to user action. This may change over time and is not safe for programmatic use.
institution_name
string
The full institution name, such as Wells Fargo
institution_id
string
The Plaid institution identifier
link_session_id
string
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
request_id
string
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation.
1plaidlink://exit
2  ?status=requires_credentials
3  &error_type=ITEM_ERROR
4  &error_code=ITEM_LOGIN_REQUIRED
5  &error_display_message=The%20credentials%20were%20not%20correct.%20Please%20try%20again.
6  &error_message=the%20credentials%20were%20not%20correct
7  &institution_id=ins_3
8  &institution_name=Chase
9  &link_session_id=79e772be-547d-4c9c-8b76-4ac4ed4c441a
10  &request_id=m8MDnv9okwxFNBV

event

The event message is analogous to the Link Web onEvent callback and is called as the user moves through the Link flow. The querystring will always contain all possible keys, though not all keys will have values. The event_name will dictate which keys are populated.

event
event_name
string
A string representing the event that has just occurred in the Link flow.
BANK_INCOME_INSIGHTS_COMPLETED
The user has completed the Assets and Bank Income Insights flow.
CLOSE_OAUTH
The user closed the third-party website or mobile app without completing the OAuth flow.
ERROR
A recoverable error occurred in the Link flow, see the error_code metadata.
EXIT
The user has exited without completing the Link flow and the exit callback is fired.
FAIL_OAUTH
The user encountered an error while completing the third-party's OAuth login flow.
HANDOFF
The user has exited Link after successfully linking an Item.
MATCHED_SELECT_INSTITUTION
The user selected an institution that was presented as a matched institution. This event can be emitted either during the Returning User Experience flow or if the institution's routing_number was provided when calling /link/token/create. To distinguish between the two scenarios, see metadata.match_reason.
MATCHED_SELECT_VERIFY_METHOD
The user selected a verification method for a matched institution. This event is emitted only during the Returning User Experience flow.
OPEN
The user has opened Link.
OPEN_MY_PLAID
The user has opened my.plaid.com. This event is only sent when Link is initialized with Assets as a product
OPEN_OAUTH
The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.
SEARCH_INSTITUTION
The user has searched for an institution.
SELECT_BRAND
The user selected a brand, e.g. Bank of America. The SELECT_BRAND event is only emitted for large financial institutions with multiple online banking portals.
SELECT_DEGRADED_INSTITUTION
The user selected an institution with a DEGRADED health status and was shown a corresponding message.
SELECT_DOWN_INSTITUTION
The user selected an institution with a DOWN health status and was shown a corresponding message.
SELECT_INSTITUTION
The user selected an institution.
SUBMIT_ACCOUNT_NUMBER
The user has submitted an account number. This event emits the account_number_mask metadata to indicate the mask of the account number the user provided.
SUBMIT_CREDENTIALS
The user has submitted credentials.
SUBMIT_DOCUMENTS
The user is being prompted to submit documents for an Income verification flow.
SUBMIT_DOCUMENTS_ERROR
The user encountered an error when submitting documents for an Income verification flow.
SUBMIT_DOCUMENTS_SUCCESS
The user has successfully submitted documents for an Income verification flow.
SUBMIT_MFA
The user has submitted MFA.
SUBMIT_ROUTING_NUMBER
The user has submitted routing number. This event emits the routing_number metadata to indicate user's routing number.
TRANSITION_VIEW
The TRANSITION_VIEW event indicates that the user has moved from one view to the next.
VIEW_DATA_TYPES
The user has viewed data types on the data transparency consent pane.
error_type
nullablestring
The error type that the user encountered. Emitted by: ERROR, EXIT.
error_code
nullablestring
The error code that the user encountered. Emitted by ERROR, EXIT.
error_message
nullablestring
The error message that the user encountered. Emitted by: ERROR, EXIT.
exit_status
nullablestring
The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT
institution_id
nullablestring
The ID of the selected institution. Emitted by: all events.
institution_name
nullablestring
The name of the selected institution. Emitted by: all events.
institution_search_query
nullablestring
The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.
is_update_mode
nullablestring
Indicates if the current Link session is an update mode session. Emitted by: OPEN.
match_reason
nullablestring
The reason this institution was matched, which will be either returning_user or routing_number. Emitted by: MATCHED_SELECT_INSTITUTION
mfa_type
nullablestring
If set, the user has encountered one of the following MFA types: code, device, questions, selections. Emitted by: SUBMIT_MFA and TRANSITION_VIEW when view_name is MFA
view_name
nullablestring
The name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW.
ACCEPT_TOS
The view showing Terms of Service in the identity verification flow.
CONNECTED
The user has connected their account.
CONSENT
We ask the user to consent to the privacy policy.
CREDENTIAL
Asking the user for their account credentials.
DATA_TRANSPARENCY
We disclose the data types being shared.
DATA_TRANSPARENCY_CONSENT
We ask the user to consent to the privacy policy and disclose data types being shared.
DOCUMENTARY_VERIFICATION
The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor).
ERROR
An error has occurred.
EXIT
Confirming if the user wishes to close Link.
KYC_CHECK
The view representing the "know your customer" step in the identity verification flow.
LOADING
Link is making a request to our servers.
MATCHED_CONSENT
We ask the matched user to consent to the privacy policy and SMS terms.
MATCHED_CREDENTIAL
We ask the matched user for their account credentials to a matched institution.
MATCHED_MFA
We ask the matched user for MFA authentication to verify their identity.
MFA
The user is asked by the institution for additional MFA authentication.
NUMBERS
The user is asked to insert their account and routing numbers.
OAUTH
The user is informed they will authenticate with the financial institution via OAuth.
RECAPTCHA
The user was presented with a Google reCAPTCHA to verify they are human.
RISK_CHECK
The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor).
SCREENING
The watchlist screening step in the identity verification flow.
SELECT_ACCOUNT
We ask the user to choose an account.
SELECT_BRAND
The user selected a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.
SELECT_INSTITUTION
We ask the user to choose their institution.
SELFIE_CHECK
The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.
VERIFY_SMS
The SMS verification step in the identity verification flow.
request_id
string
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
link_session_id
string
The link_session_id is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: all events.
timestamp
string
An ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z. Emitted by: all events.
selection
nullablestring
Either the verification method for a matched institution selected by the user or the Flexible Auth flow type selected by the user. If selection is used to describe selected verification method, then possible values are phoneotp or password; if selection is used to describe the selected Flexible Auth flow, then possible values are flow_type_manual or flow_type_instant. Emitted by: MATCHED_SELECT_VERIFY_METHOD and SELECT_AUTH_TYPE.
1plaidlink://event
2  &event_name=SELECT_INSTITUTION
3  ?error_type=ITEM_ERROR
4  &error_code=ITEM_LOGIN_REQUIRED
5  &error_message=the%20credentials%20were%20not%20correct
6  &exit_status
7  &institution_id=ins_55
8  &institution_name=HSBC
9  &institution_search_query=h
10  &mfa_type
11  &view_name=ERROR
12  &request_id
13  &link_session_id=821f45a8-854a-4dbb-8e5f-73f75350e7e7
14  &timestamp=2018-10-05T15%3A22%3A50.542Z

OAuth

Using Plaid Link with an OAuth flow requires some additional setup instructions. For details, see the OAuth Guide.

Supported platforms

Plaid officially supports WKWebView on iOS 10 or later and Chrome WebView on Android 4.4 or later.

api products transactions

Transactions

API reference for Transactions endpoints and webhooks

Retrieve and refresh 24 months of historical transaction data, including geolocation, merchant, and category information.

Endpoints
/transactions/syncGet transaction data or incremental transaction updates
/transactions/getFetch transaction data
/transactions/recurring/getFetch recurring transaction data
/transactions/refreshRefresh transaction data
/categories/getFetch all transaction categories
See also
/processor/transactions/syncGet transaction data or incremental transaction updates
/processor/transactions/getFetch transaction data
/processor/transactions/recurring/getFetch recurring transaction data
/processor/transactions/refreshRefresh transaction data
Webhooks
SYNC_UPDATES_AVAILABLENew updates available
RECURRING_TRANSACTIONS_UPDATENew recurring updates available
INITIAL_UPDATEInitial transactions ready
HISTORICAL_UPDATEHistorical transactions ready
DEFAULT_UPDATENew transactions available
TRANSACTIONS_REMOVEDDeleted transactions detected

Endpoints

/transactions/sync

If you are migrating to /transactions/sync from an existing /transactions/get integration, also refer to the Transactions Sync migration guide.

Get incremental transaction updates on an Item

This endpoint replaces /transactions/get and its associated webhooks for most common use-cases.
The /transactions/sync endpoint allows developers to subscribe to all transactions associated with an Item and get updates synchronously in a stream-like manner, using a cursor to track which updates have already been seen. /transactions/sync provides the same functionality as /transactions/get and can be used instead of /transactions/get to simplify the process of tracking transactions updates.
This endpoint provides user-authorized transaction data for credit, depository, and some loan-type accounts (only those with account subtype student; coverage may be limited). For transaction history from investments accounts, use /investments/transactions/get instead.
Returned transactions data is grouped into three types of update, indicating whether the transaction was added, removed, or modified since the last call to the API.
In the first call to /transactions/sync for an Item, the endpoint will return all historical transactions data associated with that Item up until the time of the API call (as "adds"), which then generates a next_cursor for that Item. In subsequent calls, send the next_cursor to receive only the changes that have occurred since the previous call.
Due to the potentially large number of transactions associated with an Item, results are paginated. The has_more field specifies if additional calls are necessary to fetch all available transaction updates. Call /transactions/sync with the new cursor, pulling all updates, until has_more is false.
When retrieving paginated updates, track both the next_cursor from the latest response and the original cursor from the first call in which has_more was true; if a call to /transactions/sync fails due to the TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION error, the entire pagination request loop must be restarted beginning with the cursor for the first page of the update, rather than retrying only the single request that failed.
Whenever new or updated transaction data becomes available, /transactions/sync will provide these updates. Plaid typically checks for new data multiple times a day, but these checks may occur less frequently, such as once a day, depending on the institution. An Item's status.transactions.last_successful_update field will show the timestamp of the most recent successful update. To force Plaid to check for new transactions, use the /transactions/refresh endpoint.
Note that for newly created Items, data may not be immediately available to /transactions/sync. Plaid begins preparing transactions data when the Item is created, but the process can take anywhere from a few seconds to several minutes to complete, depending on the number of transactions available.
To be alerted when new data is available, listen for the SYNC_UPDATES_AVAILABLE webhook.

transactions/sync

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
cursor
string
The cursor value represents the last update requested. Providing it will cause the response to only return changes after this update. If omitted, the entire history of updates will be returned, starting with the first-added transactions on the Item. The cursor also accepts the special value of "now", which can be used to fast-forward the cursor as part of migrating an existing Item from /transactions/get to /transactions/sync. For more information, see the Transactions sync migration guide. Note that using the "now value is not supported for any use case other than migrating existing Items from /transactions/get.
The upper-bound length of this cursor is 256 characters of base64.
count
integer
The number of transaction updates to fetch.

Default: 100
Minimum: 1
Maximum: 500
Exclusive min: false
options
object
An optional object to be used with the request. If specified, options must not be null.
include_original_description
boolean
Include the raw unparsed transaction description from the financial institution. This field is disabled by default. If you need this information in addition to the parsed data provided, contact your Plaid Account Manager or submit a Support request.

Default: false
include_personal_finance_category
boolean
Include the personal_finance_category object in the response.
All implementations are encouraged to use set this field to true and to use the personal_finance_category instead of category for more meaningful and accurate categorization.
See the taxonomy csv file for a full list of personal finance categories.

Default: false
Select Language
1// Provide a cursor from your database if you've previously
2// received one for the Item. Leave null if this is your
3// first sync call for this Item. The first request will
4// return a cursor.
5let cursor = database.getLatestCursorOrNull(itemId);
6
7// New transaction updates since "cursor"
8let added: Array<Transaction> = [];
9let modified: Array<Transaction> = [];
10// Removed transaction ids
11let removed: Array<RemovedTransaction> = [];
12let hasMore = true;
13
14// Iterate through each page of new transaction updates for item
15while (hasMore) {
16  const request: TransactionsSyncRequest = {
17    access_token: accessToken,
18    cursor: cursor,
19    options: {include_personal_finance_category: true},
20  };
21  const response = await client.transactionsSync(request);
22  const data = response.data;
23
24  // Add this page of results
25  added = added.concat(data.added);
26  modified = modified.concat(data.modified);
27  removed = removed.concat(data.removed);
28
29  hasMore = data.has_more;
30
31  // Update cursor to the next cursor
32  cursor = data.next_cursor;
33}
34
35// Persist cursor and updated data
36database.applyUpdates(itemId, added, modified, removed, cursor);
transactions/sync

Response fields and example

added
[object]
Transactions that have been added to the Item since cursor ordered by ascending last modified time.
account_id
string
The ID of the account in which this transaction occurred.
amount
number
The settled value of the transaction, denominated in the transactions's currency, as stated in iso_currency_code or unofficial_currency_code. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the transaction. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the transaction. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
category
nullable[string]
A hierarchical array of the categories to which this transaction belongs. For a full list of categories, see /categories/get.
All Transactions implementations are recommended to use the new personal_finance_category instead of category. personal_finance_category provides more meaningful categorization and greater accuracy.
If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
category_id
nullablestring
The ID of the category to which this transaction belongs. For a full list of categories, see /categories/get.
All Transactions implementations are recommended to use the new personal_finance_category instead of category_id, as it provides greater accuracy and more meaningful categorization.
If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
check_number
nullablestring
The check number of the transaction. This field is only populated for check transactions.
date
string
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). To receive information about the date that a posted transaction was initiated, see the authorized_date field.

Format: date
location
object
A representation of where a transaction took place
address
nullablestring
The street address where the transaction occurred.
city
nullablestring
The city where the transaction occurred.
region
nullablestring
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.
postal_code
nullablestring
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code where the transaction occurred.
lat
nullablenumber
The latitude where the transaction occurred.

Format: double
lon
nullablenumber
The longitude where the transaction occurred.

Format: double
store_number
nullablestring
The merchant defined store number where the transaction occurred.
name
string
The merchant name or transaction description.
If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, this field will always appear. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
merchant_name
nullablestring
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.
original_description
nullablestring
The string returned by the financial institution to describe the transaction. For transactions returned by /transactions/sync or /transactions/get, this field is in beta and will be omitted unless the client is both enrolled in the closed beta program and has set options.include_original_description to true.
payment_meta
object
Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null.
If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, the payment_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
reference_number
nullablestring
The transaction reference number supplied by the financial institution.
ppd_id
nullablestring
The ACH PPD ID for the payer.
payee
nullablestring
For transfers, the party that is receiving the transaction.
by_order_of
nullablestring
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.
payer
nullablestring
For transfers, the party that is paying the transaction.
payment_method
nullablestring
The type of transfer, e.g. 'ACH'
payment_processor
nullablestring
The name of the payment processor
reason
nullablestring
The payer-supplied description of the transfer.
pending
boolean
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.
pending_transaction_id
nullablestring
The ID of a posted transaction's associated pending transaction, where applicable.
account_owner
nullablestring
The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts.
transaction_id
string
The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive.
transaction_type
deprecatedstring
Please use the payment_channel field, transaction_type will be deprecated in the future.
digital: transactions that took place online.
place: transactions that were made at a physical location.
special: transactions that relate to banks, e.g. fees or deposits.
unresolved: transactions that do not fit into the other three types.

Possible values: digital, place, special, unresolved
authorized_date
nullablestring
The date that the transaction was authorized. For posted transactions, the date field will indicate the posted date, but authorized_date will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized_date, when available, is generally preferable to use over the date field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an ISO 8601 format ( YYYY-MM-DD ).

Format: date
authorized_datetime
nullablestring
Date and time when a transaction was authorized in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For posted transactions, the datetime field will indicate the posted date, but authorized_datetime will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized_datetime, when available, is generally preferable to use over the datetime field for posted transactions, as it will generally represent the date the user actually made the transaction.
This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later.

Format: date-time
datetime
nullablestring
Date and time when a transaction was posted in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For the date that the transaction was initiated, rather than posted, see the authorized_datetime field.
This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later.

Format: date-time
payment_channel
string
The channel used to make a payment. online: transactions that took place online.
in store: transactions that were made at a physical location.
other: transactions that relate to banks, e.g. fees or deposits.
This field replaces the transaction_type field.

Possible values: online, in store, other
personal_finance_category
nullableobject
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases.
See the taxonomy csv file for a full list of personal finance categories.
primary
string
A high level category that communicates the broad category of the transaction.
detailed
string
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.
confidence_level
nullablestring
Note: This field is only available for /transactions/enrich endpoint currently. A description of how confident we are that the provided categories accurately describe the transaction intent.
VERY_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: Error
transaction_code
nullablestring
An identifier classifying the transaction type.
This field is only populated for European institutions. For institutions in the US and Canada, this field is set to null.
adjustment: Bank adjustment
atm: Cash deposit or withdrawal via an automated teller machine
bank charge: Charge or fee levied by the institution
bill payment: Payment of a bill
cash: Cash deposit or withdrawal
cashback: Cash withdrawal while making a debit card purchase
cheque: Document ordering the payment of money to another person or organization
direct debit: Automatic withdrawal of funds initiated by a third party at a regular interval
interest: Interest earned or incurred
purchase: Purchase made with a debit or credit card
standing order: Payment instructed by the account holder to a third party at a regular interval
transfer: Transfer of money between accounts

Possible values: adjustment, atm, bank charge, bill payment, cash, cashback, cheque, direct debit, interest, purchase, standing order, transfer, null
modified
[object]
Transactions that have been modified on the Item since cursor ordered by ascending last modified time.
account_id
string
The ID of the account in which this transaction occurred.
amount
number
The settled value of the transaction, denominated in the transactions's currency, as stated in iso_currency_code or unofficial_currency_code. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the transaction. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the transaction. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
category
nullable[string]
A hierarchical array of the categories to which this transaction belongs. For a full list of categories, see /categories/get.
All Transactions implementations are recommended to use the new personal_finance_category instead of category. personal_finance_category provides more meaningful categorization and greater accuracy.
If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
category_id
nullablestring
The ID of the category to which this transaction belongs. For a full list of categories, see /categories/get.
All Transactions implementations are recommended to use the new personal_finance_category instead of category_id, as it provides greater accuracy and more meaningful categorization.
If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
check_number
nullablestring
The check number of the transaction. This field is only populated for check transactions.
date
string
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). To receive information about the date that a posted transaction was initiated, see the authorized_date field.

Format: date
location
object
A representation of where a transaction took place
address
nullablestring
The street address where the transaction occurred.
city
nullablestring
The city where the transaction occurred.
region
nullablestring
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.
postal_code
nullablestring
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code where the transaction occurred.
lat
nullablenumber
The latitude where the transaction occurred.

Format: double
lon
nullablenumber
The longitude where the transaction occurred.

Format: double
store_number
nullablestring
The merchant defined store number where the transaction occurred.
name
string
The merchant name or transaction description.
If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, this field will always appear. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
merchant_name
nullablestring
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.
original_description
nullablestring
The string returned by the financial institution to describe the transaction. For transactions returned by /transactions/sync or /transactions/get, this field is in beta and will be omitted unless the client is both enrolled in the closed beta program and has set options.include_original_description to true.
payment_meta
object
Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null.
If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, the payment_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
reference_number
nullablestring
The transaction reference number supplied by the financial institution.
ppd_id
nullablestring
The ACH PPD ID for the payer.
payee
nullablestring
For transfers, the party that is receiving the transaction.
by_order_of
nullablestring
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.
payer
nullablestring
For transfers, the party that is paying the transaction.
payment_method
nullablestring
The type of transfer, e.g. 'ACH'
payment_processor
nullablestring
The name of the payment processor
reason
nullablestring
The payer-supplied description of the transfer.
pending
boolean
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.
pending_transaction_id
nullablestring
The ID of a posted transaction's associated pending transaction, where applicable.
account_owner
nullablestring
The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts.
transaction_id
string
The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive.
transaction_type
deprecatedstring
Please use the payment_channel field, transaction_type will be deprecated in the future.
digital: transactions that took place online.
place: transactions that were made at a physical location.
special: transactions that relate to banks, e.g. fees or deposits.
unresolved: transactions that do not fit into the other three types.

Possible values: digital, place, special, unresolved
authorized_date
nullablestring
The date that the transaction was authorized. For posted transactions, the date field will indicate the posted date, but authorized_date will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized_date, when available, is generally preferable to use over the date field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an ISO 8601 format ( YYYY-MM-DD ).

Format: date
authorized_datetime
nullablestring
Date and time when a transaction was authorized in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For posted transactions, the datetime field will indicate the posted date, but authorized_datetime will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized_datetime, when available, is generally preferable to use over the datetime field for posted transactions, as it will generally represent the date the user actually made the transaction.
This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later.

Format: date-time
datetime
nullablestring
Date and time when a transaction was posted in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For the date that the transaction was initiated, rather than posted, see the authorized_datetime field.
This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later.

Format: date-time
payment_channel
string
The channel used to make a payment. online: transactions that took place online.
in store: transactions that were made at a physical location.
other: transactions that relate to banks, e.g. fees or deposits.
This field replaces the transaction_type field.

Possible values: online, in store, other
personal_finance_category
nullableobject
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases.
See the taxonomy csv file for a full list of personal finance categories.
primary
string
A high level category that communicates the broad category of the transaction.
detailed
string
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.
confidence_level
nullablestring
Note: This field is only available for /transactions/enrich endpoint currently. A description of how confident we are that the provided categories accurately describe the transaction intent.
VERY_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: Error
transaction_code
nullablestring
An identifier classifying the transaction type.
This field is only populated for European institutions. For institutions in the US and Canada, this field is set to null.
adjustment: Bank adjustment
atm: Cash deposit or withdrawal via an automated teller machine
bank charge: Charge or fee levied by the institution
bill payment: Payment of a bill
cash: Cash deposit or withdrawal
cashback: Cash withdrawal while making a debit card purchase
cheque: Document ordering the payment of money to another person or organization
direct debit: Automatic withdrawal of funds initiated by a third party at a regular interval
interest: Interest earned or incurred
purchase: Purchase made with a debit or credit card
standing order: Payment instructed by the account holder to a third party at a regular interval
transfer: Transfer of money between accounts

Possible values: adjustment, atm, bank charge, bill payment, cash, cashback, cheque, direct debit, interest, purchase, standing order, transfer, null
removed
[object]
Transactions that have been removed from the Item since cursor ordered by ascending last modified time.
transaction_id
string
The ID of the removed transaction.
next_cursor
string
Cursor used for fetching any future updates after the latest update provided in this response. The cursor obtained after all pages have been pulled (indicated by has_more being false) will be valid for at least 1 year. This cursor should be persisted for later calls. If transactions are not yet available, this will be an empty string.
has_more
boolean
Represents if more than requested count of transaction updates exist. If true, the additional updates can be fetched by making an additional request with cursor set to next_cursor. If has_more is true, it’s important to pull all available pages, to make it less likely for underlying data changes to conflict with pagination.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "added": [
3    {
4      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
5      "amount": 2307.21,
6      "iso_currency_code": "USD",
7      "unofficial_currency_code": null,
8      "category": [
9        "Shops",
10        "Computers and Electronics"
11      ],
12      "category_id": "19013000",
13      "check_number": null,
14      "date": "2022-02-03",
15      "datetime": "2022-02-03T11:00:00Z",
16      "authorized_date": "2022-02-03",
17      "authorized_datetime": "2022-02-03T10:34:50Z",
18      "location": {
19        "address": "300 Post St",
20        "city": "San Francisco",
21        "region": "CA",
22        "postal_code": "94108",
23        "country": "US",
24        "lat": 40.740352,
25        "lon": -74.001761,
26        "store_number": "1235"
27      },
28      "name": "Apple Store",
29      "merchant_name": "Apple",
30      "payment_meta": {
31        "by_order_of": null,
32        "payee": null,
33        "payer": null,
34        "payment_method": null,
35        "payment_processor": null,
36        "ppd_id": null,
37        "reason": null,
38        "reference_number": null
39      },
40      "payment_channel": "in store",
41      "pending": false,
42      "pending_transaction_id": null,
43      "personal_finance_category": {
44        "primary": "GENERAL_MERCHANDISE",
45        "detailed": "GENERAL_MERCHANDISE_ELECTRONICS"
46      },
47      "account_owner": null,
48      "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
49      "transaction_code": null
50    }
51  ],
52  "modified": [
53    {
54      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
55      "amount": 98.05,
56      "iso_currency_code": "USD",
57      "unofficial_currency_code": null,
58      "category": [
59        "Service",
60        "Utilities",
61        "Electric"
62      ],
63      "category_id": "18068005",
64      "check_number": null,
65      "date": "2022-02-28",
66      "datetime": "2022-02-28T11:00:00Z",
67      "authorized_date": "2022-02-28",
68      "authorized_datetime": "2022-02-28T10:34:50Z",
69      "location": {
70        "address": null,
71        "city": null,
72        "region": null,
73        "postal_code": null,
74        "country": null,
75        "lat": null,
76        "lon": null,
77        "store_number": null
78      },
79      "name": "ConEd Bill Payment",
80      "merchant_name": "ConEd",
81      "payment_meta": {
82        "by_order_of": null,
83        "payee": null,
84        "payer": null,
85        "payment_method": null,
86        "payment_processor": null,
87        "ppd_id": null,
88        "reason": null,
89        "reference_number": null
90      },
91      "payment_channel": "online",
92      "pending": false,
93      "pending_transaction_id": null,
94      "personal_finance_category": {
95        "primary": "RENT_AND_UTILITIES",
96        "detailed": "RENT_AND_UTILITIES_GAS_AND_ELECTRICITY"
97      },
98      "account_owner": null,
99      "transaction_id": "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0",
100      "transaction_code": null
101    }
102  ],
103  "removed": [
104    {
105      "transaction_id": "CmdQTNgems8BT1B7ibkoUXVPyAeehT3Tmzk0l"
106    }
107  ],
108  "next_cursor": "tVUUL15lYQN5rBnfDIc1I8xudpGdIlw9nsgeXWvhOfkECvUeR663i3Dt1uf/94S8ASkitgLcIiOSqNwzzp+bh89kirazha5vuZHBb2ZA5NtCDkkV",
109  "has_more": false,
110  "request_id": "45QSn"
111}
Was this helpful?

/transactions/get

Get transaction data

Note: All new implementations are encouraged to use /transactions/sync rather than /transactions/get. /transactions/sync provides the same functionality as /transactions/get and improves developer ease-of-use for handling transactions updates.
The /transactions/get endpoint allows developers to receive user-authorized transaction data for credit, depository, and some loan-type accounts (only those with account subtype student; coverage may be limited). For transaction history from investments accounts, use the Investments endpoint instead. Transaction data is standardized across financial institutions, and in many cases transactions are linked to a clean name, entity type, location, and category. Similarly, account data is standardized and returned with a clean name, number, balance, and other meta information where available.
Transactions are returned in reverse-chronological order, and the sequence of transaction ordering is stable and will not shift. Transactions are not immutable and can also be removed altogether by the institution; a removed transaction will no longer appear in /transactions/get. For more details, see Pending and posted transactions.
Due to the potentially large number of transactions associated with an Item, results are paginated. Manipulate the count and offset parameters in conjunction with the total_transactions response body field to fetch all available transactions.
Data returned by /transactions/get will be the data available for the Item as of the most recent successful check for new transactions. Plaid typically checks for new data multiple times a day, but these checks may occur less frequently, such as once a day, depending on the institution. An Item's status.transactions.last_successful_update field will show the timestamp of the most recent successful update. To force Plaid to check for new transactions, you can use the /transactions/refresh endpoint.
Note that data may not be immediately available to /transactions/get. Plaid will begin to prepare transactions data upon Item link, if Link was initialized with transactions, or upon the first call to /transactions/get, if it wasn't. To be alerted when transaction data is ready to be fetched, listen for the INITIAL_UPDATE and HISTORICAL_UPDATE webhooks. If no transaction history is ready when /transactions/get is called, it will return a PRODUCT_NOT_READY error.

transactions/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
options
object
An optional object to be used with the request. If specified, options must not be null.
account_ids
[string]
A list of account_ids to retrieve for the Item
Note: An error will be returned if a provided account_id is not associated with the Item.
count
integer
The number of transactions to fetch.

Default: 100
Minimum: 1
Maximum: 500
Exclusive min: false
offset
integer
The number of transactions to skip. The default value is 0.

Default: 0
Minimum: 0
include_original_description
boolean
Include the raw unparsed transaction description from the financial institution. This field is disabled by default. If you need this information in addition to the parsed data provided, contact your Plaid Account Manager, or submit a Support request .

Default: false
include_personal_finance_category
boolean
Include the personal_finance_category object in the response.
All implementations are encouraged to set this field to true and use the personal_finance_category instead of category. Personal finance categories are the preferred categorization system for transactions, providing higher accuracy and more meaningful categories.
See the taxonomy csv file for a full list of personal finance categories.

Default: false
access_token
requiredstring
The access token associated with the Item data is being requested for.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
start_date
requiredstring
The earliest date for which data should be returned. Dates should be formatted as YYYY-MM-DD.

Format: date
end_date
requiredstring
The latest date for which data should be returned. Dates should be formatted as YYYY-MM-DD.

Format: date
Select group for content switcher
Select Language
1const request: TransactionsGetRequest = {
2  access_token: accessToken,
3  start_date: '2018-01-01',
4  end_date: '2020-02-01',
5  options: {
6    include_personal_finance_category: true
7  }
8};
9try {
10  const response = await client.transactionsGet(request);
11  let transactions = response.data.transactions;
12  const total_transactions = response.data.total_transactions;
13  // Manipulate the offset parameter to paginate
14  // transactions and retrieve all available data
15  while (transactions.length < total_transactions) {
16    const paginatedRequest: TransactionsGetRequest = {
17      access_token: accessToken,
18      start_date: '2018-01-01',
19      end_date: '2020-02-01',
20      options: {
21        offset: transactions.length,
22        include_personal_finance_category: true
23      },
24    };
25    const paginatedResponse = await client.transactionsGet(paginatedRequest);
26    transactions = transactions.concat(
27      paginatedResponse.data.transactions,
28    );
29  }
30} catch((err) => {
31  // handle error
32}
transactions/get

Response fields and example

accounts
[object]
An array containing the accounts associated with the Item for which transactions are being returned. Each transaction can be mapped to its corresponding account via the account_id field.
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullablenumber
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullablenumber
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullablenumber
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullablestring
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
transactions
[object]
An array containing transactions from the account. Transactions are returned in reverse chronological order, with the most recent at the beginning of the array. The maximum number of transactions returned is determined by the count parameter.
account_id
string
The ID of the account in which this transaction occurred.
amount
number
The settled value of the transaction, denominated in the transactions's currency, as stated in iso_currency_code or unofficial_currency_code. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the transaction. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the transaction. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
category
nullable[string]
A hierarchical array of the categories to which this transaction belongs. For a full list of categories, see /categories/get.
All Transactions implementations are recommended to use the new personal_finance_category instead of category. personal_finance_category provides more meaningful categorization and greater accuracy.
If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
category_id
nullablestring
The ID of the category to which this transaction belongs. For a full list of categories, see /categories/get.
All Transactions implementations are recommended to use the new personal_finance_category instead of category_id, as it provides greater accuracy and more meaningful categorization.
If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
check_number
nullablestring
The check number of the transaction. This field is only populated for check transactions.
date
string
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). To receive information about the date that a posted transaction was initiated, see the authorized_date field.

Format: date
location
object
A representation of where a transaction took place
address
nullablestring
The street address where the transaction occurred.
city
nullablestring
The city where the transaction occurred.
region
nullablestring
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.
postal_code
nullablestring
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code where the transaction occurred.
lat
nullablenumber
The latitude where the transaction occurred.

Format: double
lon
nullablenumber
The longitude where the transaction occurred.

Format: double
store_number
nullablestring
The merchant defined store number where the transaction occurred.
name
string
The merchant name or transaction description.
If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, this field will always appear. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
merchant_name
nullablestring
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.
original_description
nullablestring
The string returned by the financial institution to describe the transaction. For transactions returned by /transactions/sync or /transactions/get, this field is in beta and will be omitted unless the client is both enrolled in the closed beta program and has set options.include_original_description to true.
payment_meta
object
Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null.
If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, the payment_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
reference_number
nullablestring
The transaction reference number supplied by the financial institution.
ppd_id
nullablestring
The ACH PPD ID for the payer.
payee
nullablestring
For transfers, the party that is receiving the transaction.
by_order_of
nullablestring
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.
payer
nullablestring
For transfers, the party that is paying the transaction.
payment_method
nullablestring
The type of transfer, e.g. 'ACH'
payment_processor
nullablestring
The name of the payment processor
reason
nullablestring
The payer-supplied description of the transfer.
pending
boolean
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.
pending_transaction_id
nullablestring
The ID of a posted transaction's associated pending transaction, where applicable.
account_owner
nullablestring
The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts.
transaction_id
string
The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive.
transaction_type
deprecatedstring
Please use the payment_channel field, transaction_type will be deprecated in the future.
digital: transactions that took place online.
place: transactions that were made at a physical location.
special: transactions that relate to banks, e.g. fees or deposits.
unresolved: transactions that do not fit into the other three types.

Possible values: digital, place, special, unresolved
authorized_date
nullablestring
The date that the transaction was authorized. For posted transactions, the date field will indicate the posted date, but authorized_date will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized_date, when available, is generally preferable to use over the date field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an ISO 8601 format ( YYYY-MM-DD ).

Format: date
authorized_datetime
nullablestring
Date and time when a transaction was authorized in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For posted transactions, the datetime field will indicate the posted date, but authorized_datetime will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized_datetime, when available, is generally preferable to use over the datetime field for posted transactions, as it will generally represent the date the user actually made the transaction.
This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later.

Format: date-time
datetime
nullablestring
Date and time when a transaction was posted in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). For the date that the transaction was initiated, rather than posted, see the authorized_datetime field.
This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later.

Format: date-time
payment_channel
string
The channel used to make a payment. online: transactions that took place online.
in store: transactions that were made at a physical location.
other: transactions that relate to banks, e.g. fees or deposits.
This field replaces the transaction_type field.

Possible values: online, in store, other
personal_finance_category
nullableobject
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases.
See the taxonomy csv file for a full list of personal finance categories.
primary
string
A high level category that communicates the broad category of the transaction.
detailed
string
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.
confidence_level
nullablestring
Note: This field is only available for /transactions/enrich endpoint currently. A description of how confident we are that the provided categories accurately describe the transaction intent.
VERY_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: Error
transaction_code
nullablestring
An identifier classifying the transaction type.
This field is only populated for European institutions. For institutions in the US and Canada, this field is set to null.
adjustment: Bank adjustment
atm: Cash deposit or withdrawal via an automated teller machine
bank charge: Charge or fee levied by the institution
bill payment: Payment of a bill
cash: Cash deposit or withdrawal
cashback: Cash withdrawal while making a debit card purchase
cheque: Document ordering the payment of money to another person or organization
direct debit: Automatic withdrawal of funds initiated by a third party at a regular interval
interest: Interest earned or incurred
purchase: Purchase made with a debit or credit card
standing order: Payment instructed by the account holder to a third party at a regular interval
transfer: Transfer of money between accounts

Possible values: adjustment, atm, bank charge, bill payment, cash, cashback, cheque, direct debit, interest, purchase, standing order, transfer, null
total_transactions
integer
The total number of transactions available within the date range specified. If total_transactions is larger than the size of the transactions array, more transactions are available and can be fetched via manipulating the offset parameter.
item
object
Metadata about the Item.
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
nullablestring
The Plaid Institution ID associated with the Item. Field is null for Items created via Same Day Micro-deposits.
webhook
nullablestring
The URL registered to receive webhooks for the Item.
error
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
available_products
[string]
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
billed_products
[string]
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available_products. Note - billed_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
products
[string]
A list of initialized products for the Item. In almost all cases, this will be the same as the billed_products field. For some products, it is possible for the product to be initialized on an Item but not yet billed (e.g. Assets, before /asset_report/create has been called), in which case the product may appear in products but not in billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consented_products
[string]
A list of products that have gone through consent collection for the Item. Only present for those enabled in the Data Transparency beta. If you are not enrolled in Data Transparency, this field is not used.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consent_expiration_time
nullablestring
The RFC 3339 timestamp after which the consent provided by the end user will expire. Upon consent expiration, the item will enter the ITEM_LOGIN_REQUIRED error state. To circumvent the ITEM_LOGIN_REQUIRED error and maintain continuous consent, the end user can reauthenticate via Link’s update mode in advance of the consent expiration time.
Note - This is only relevant for certain OAuth-based institutions. For all other institutions, this field will be null.

Format: date-time
update_type
string
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication.
background - Item can be updated in the background
user_present_required - Item requires user interaction to be updated

Possible values: background, user_present_required
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "accounts": [
3    {
4      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
5      "balances": {
6        "available": 110,
7        "current": 110,
8        "iso_currency_code": "USD",
9        "limit": null,
10        "unofficial_currency_code": null
11      },
12      "mask": "0000",
13      "name": "Plaid Checking",
14      "official_name": "Plaid Gold Standard 0% Interest Checking",
15      "subtype": "checking",
16      "type": "depository"
17    }
18  ],
19  "transactions": [
20    {
21      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
22      "amount": 2307.21,
23      "iso_currency_code": "USD",
24      "unofficial_currency_code": null,
25      "category": [
26        "Shops",
27        "Computers and Electronics"
28      ],
29      "category_id": "19013000",
30      "check_number": null,
31      "date": "2017-01-29",
32      "datetime": "2017-01-27T11:00:00Z",
33      "authorized_date": "2017-01-27",
34      "authorized_datetime": "2017-01-27T10:34:50Z",
35      "location": {
36        "address": "300 Post St",
37        "city": "San Francisco",
38        "region": "CA",
39        "postal_code": "94108",
40        "country": "US",
41        "lat": 40.740352,
42        "lon": -74.001761,
43        "store_number": "1235"
44      },
45      "name": "Apple Store",
46      "merchant_name": "Apple",
47      "payment_meta": {
48        "by_order_of": null,
49        "payee": null,
50        "payer": null,
51        "payment_method": null,
52        "payment_processor": null,
53        "ppd_id": null,
54        "reason": null,
55        "reference_number": null
56      },
57      "payment_channel": "in store",
58      "pending": false,
59      "pending_transaction_id": null,
60      "personal_finance_category": {
61        "primary": "GENERAL_MERCHANDISE",
62        "detailed": "GENERAL_MERCHANDISE_ELECTRONICS"
63      },
64      "account_owner": null,
65      "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
66      "transaction_code": null,
67      "transaction_type": "place"
68    }
69  ],
70  "item": {
71    "available_products": [
72      "balance",
73      "identity",
74      "investments"
75    ],
76    "billed_products": [
77      "assets",
78      "auth",
79      "liabilities",
80      "transactions"
81    ],
82    "consent_expiration_time": null,
83    "error": null,
84    "institution_id": "ins_3",
85    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
86    "update_type": "background",
87    "webhook": "https://www.genericwebhookurl.com/webhook"
88  },
89  "total_transactions": 1,
90  "request_id": "45QSn"
91}
Was this helpful?

/transactions/recurring/get

Fetch recurring transaction streams

The /transactions/recurring/get endpoint allows developers to receive a summary of the recurring outflow and inflow streams (expenses and deposits) from a user’s checking, savings or credit card accounts. Additionally, Plaid provides key insights about each recurring stream including the category, merchant, last amount, and more. Developers can use these insights to build tools and experiences that help their users better manage cash flow, monitor subscriptions, reduce spend, and stay on track with bill payments.
This endpoint is offered as an add-on to Transactions. To request access to this endpoint, submit a product access request or contact your Plaid account manager.
This endpoint can only be called on an Item that has already been initialized with Transactions (either during Link, by specifying it in /link/token/create; or after Link, by calling /transactions/get or /transactions/sync). Once all historical transactions have been fetched, call /transactions/recurring/get to receive the Recurring Transactions streams and subscribe to the RECURRING_TRANSACTIONS_UPDATE webhook. To know when historical transactions have been fetched, if you are using /transactions/sync listen for the SYNC_UPDATES_AVAILABLE webhook and check that the historical_update_complete field in the payload is true. If using /transactions/get, listen for the HISTORICAL_UPDATE webhook.
After the initial call, you can call /transactions/recurring/get endpoint at any point in the future to retrieve the latest summary of recurring streams. Listen to the RECURRING_TRANSACTIONS_UPDATE webhook to be notified when new updates are available.

transactions/recurring/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
options
object
An optional object to be used with the request. If specified, options must not be null.
include_personal_finance_category
boolean
Include the personal_finance_category object for each transaction stream in the response.
All implementations are encouraged to set this field to true and to use the personal_finance_category field instead of category. Personal finance categories are the preferred categorization system for transactions, providing higher accuracy and more meaningful categories.
See the taxonomy csv file for a full list of personal finance categories.

Default: false
account_ids
required[string]
A list of account_ids to retrieve for the Item
Note: An error will be returned if a provided account_id is not associated with the Item.
Select Language
1const request: TransactionsGetRequest = {
2  access_token: accessToken,
3  account_ids : accountIds,
4  options: { 
5    include_personal_finance_category: true
6  }
7};
8try {
9  const response = await client.transactionsRecurringGet(request);
10  let inflowStreams = response.data.inflowStreams;
11  let outflowStreams = response.data.outflowStreams;
12  }
13} catch((err) => {
14  // handle error
15}
transactions/recurring/get

Response fields and example

inflow_streams
[object]
An array of depository transaction streams.
account_id
string
The ID of the account to which the stream belongs
stream_id
string
A unique id for the stream
category
[string]
A hierarchical array of the categories to which this transaction belongs. See Categories.
All implementations are encouraged to use the new personal_finance_category instead of category. personal_finance_category provides more meaningful categorization and greater accuracy.
category_id
string
The ID of the category to which this transaction belongs. See Categories.
All implementations are encouraged to use the new personal_finance_category instead of category. personal_finance_category provides more meaningful categorization and greater accuracy.
description
string
A description of the transaction stream.
merchant_name
nullablestring
The merchant associated with the transaction stream.
first_date
string
The posted date of the earliest transaction in the stream.

Format: date
last_date
string
The posted date of the latest transaction in the stream.

Format: date
frequency
string
Describes the frequency of the transaction stream.
WEEKLY: Assigned to a transaction stream that occurs approximately every week.
BIWEEKLY: Assigned to a transaction stream that occurs approximately every 2 weeks.
SEMI_MONTHLY: Assigned to a transaction stream that occurs approximately twice per month. This frequency is typically seen for inflow transaction streams.
MONTHLY: Assigned to a transaction stream that occurs approximately every month.
ANNUALLY: Assigned to a transaction stream that occurs approximately every year.
UNKNOWN: Assigned to a transaction stream that does not fit any of the pre-defined frequencies.

Possible values: UNKNOWN, WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY, ANNUALLY
transaction_ids
[string]
An array of Plaid transaction IDs belonging to the stream, sorted by posted date.
average_amount
object
Object with data pertaining to an amount on the transaction stream.
amount
number
Represents the numerical value of an amount.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the amount. Always null if unofficial_currency_code is non-null.
See the currency code schema for a full listing of supported iso_currency_codes.
unofficial_currency_code
nullablestring
The unofficial currency code of the amount. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
last_amount
object
Object with data pertaining to an amount on the transaction stream.
amount
number
Represents the numerical value of an amount.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the amount. Always null if unofficial_currency_code is non-null.
See the currency code schema for a full listing of supported iso_currency_codes.
unofficial_currency_code
nullablestring
The unofficial currency code of the amount. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
is_active
boolean
Indicates whether the transaction stream is still live.
status
string
The current status of the transaction stream.
MATURE: A MATURE recurring stream should have at least 3 transactions and happen on a regular cadence (For Annual recurring stream, we will mark it MATURE after 2 instances).
EARLY_DETECTION: When a recurring transaction first appears in the transaction history and before it fulfills the requirement of a mature stream, the status will be EARLY_DETECTION.
TOMBSTONED: A stream that was previously in the EARLY_DETECTION status will move to the TOMBSTONED status when no further transactions were found at the next expected date.
UNKNOWN: A stream is assigned an UNKNOWN status when none of the other statuses are applicable.

Possible values: UNKNOWN, MATURE, EARLY_DETECTION, TOMBSTONED
personal_finance_category
nullableobject
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases.
See the taxonomy csv file for a full list of personal finance categories.
primary
string
A high level category that communicates the broad category of the transaction.
detailed
string
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.
confidence_level
nullablestring
Note: This field is only available for /transactions/enrich endpoint currently. A description of how confident we are that the provided categories accurately describe the transaction intent.
VERY_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: Error
outflow_streams
[object]
An array of expense transaction streams.
account_id
string
The ID of the account to which the stream belongs
stream_id
string
A unique id for the stream
category
[string]
A hierarchical array of the categories to which this transaction belongs. See Categories.
All implementations are encouraged to use the new personal_finance_category instead of category. personal_finance_category provides more meaningful categorization and greater accuracy.
category_id
string
The ID of the category to which this transaction belongs. See Categories.
All implementations are encouraged to use the new personal_finance_category instead of category. personal_finance_category provides more meaningful categorization and greater accuracy.
description
string
A description of the transaction stream.
merchant_name
nullablestring
The merchant associated with the transaction stream.
first_date
string
The posted date of the earliest transaction in the stream.

Format: date
last_date
string
The posted date of the latest transaction in the stream.

Format: date
frequency
string
Describes the frequency of the transaction stream.
WEEKLY: Assigned to a transaction stream that occurs approximately every week.
BIWEEKLY: Assigned to a transaction stream that occurs approximately every 2 weeks.
SEMI_MONTHLY: Assigned to a transaction stream that occurs approximately twice per month. This frequency is typically seen for inflow transaction streams.
MONTHLY: Assigned to a transaction stream that occurs approximately every month.
ANNUALLY: Assigned to a transaction stream that occurs approximately every year.
UNKNOWN: Assigned to a transaction stream that does not fit any of the pre-defined frequencies.

Possible values: UNKNOWN, WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY, ANNUALLY
transaction_ids
[string]
An array of Plaid transaction IDs belonging to the stream, sorted by posted date.
average_amount
object
Object with data pertaining to an amount on the transaction stream.
amount
number
Represents the numerical value of an amount.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the amount. Always null if unofficial_currency_code is non-null.
See the currency code schema for a full listing of supported iso_currency_codes.
unofficial_currency_code
nullablestring
The unofficial currency code of the amount. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
last_amount
object
Object with data pertaining to an amount on the transaction stream.
amount
number
Represents the numerical value of an amount.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the amount. Always null if unofficial_currency_code is non-null.
See the currency code schema for a full listing of supported iso_currency_codes.
unofficial_currency_code
nullablestring
The unofficial currency code of the amount. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
is_active
boolean
Indicates whether the transaction stream is still live.
status
string
The current status of the transaction stream.
MATURE: A MATURE recurring stream should have at least 3 transactions and happen on a regular cadence (For Annual recurring stream, we will mark it MATURE after 2 instances).
EARLY_DETECTION: When a recurring transaction first appears in the transaction history and before it fulfills the requirement of a mature stream, the status will be EARLY_DETECTION.
TOMBSTONED: A stream that was previously in the EARLY_DETECTION status will move to the TOMBSTONED status when no further transactions were found at the next expected date.
UNKNOWN: A stream is assigned an UNKNOWN status when none of the other statuses are applicable.

Possible values: UNKNOWN, MATURE, EARLY_DETECTION, TOMBSTONED
personal_finance_category
nullableobject
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases.
See the taxonomy csv file for a full list of personal finance categories.
primary
string
A high level category that communicates the broad category of the transaction.
detailed
string
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.
confidence_level
nullablestring
Note: This field is only available for /transactions/enrich endpoint currently. A description of how confident we are that the provided categories accurately describe the transaction intent.
VERY_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: Error
updated_datetime
string
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time transaction streams for the given account were updated on

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "updated_datetime": "2022-05-01T00:00:00Z",
3  "inflow_streams": [
4    {
5      "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
6      "stream_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nc",
7      "category": [
8        "Transfer",
9        "Payroll"
10      ],
11      "category_id": "21009000",
12      "description": "Platypus Payroll",
13      "merchant_name": null,
14      "personal_finance_category": {
15        "detailed": "INCOME_WAGES",
16        "primary": "INCOME"
17      },
18      "first_date": "2022-02-28",
19      "last_date": "2022-04-30",
20      "frequency": "SEMI_MONTHLY",
21      "transaction_ids": [
22        "nkeaNrDGrhdo6c4qZWDA8ekuIPuJ4Avg5nKfw",
23        "EfC5ekksdy30KuNzad2tQupW8WIPwvjXGbGHL",
24        "ozfvj3FFgp6frbXKJGitsDzck5eWQH7zOJBYd",
25        "QvdDE8AqVWo3bkBZ7WvCd7LskxVix8Q74iMoK",
26        "uQozFPfMzibBouS9h9tz4CsyvFll17jKLdPAF"
27      ],
28      "average_amount": {
29        "amount": -800,
30        "iso_currency_code": "USD",
31        "unofficial_currency_code": null
32      },
33      "last_amount": {
34        "amount": -1000,
35        "iso_currency_code": "USD",
36        "unofficial_currency_code": null
37      },
38      "is_active": true,
39      "status": "MATURE"
40    }
41  ],
42  "outflow_streams": [
43    {
44      "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDff",
45      "stream_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nd",
46      "category": [
47        "Service",
48        "Utilities",
49        "Electric"
50      ],
51      "category_id": "18068005",
52      "description": "ConEd Bill Payment",
53      "merchant_name": "ConEd",
54      "personal_finance_category": {
55        "detailed": "RENT_AND_UTILITIES_GAS_AND_ELECTRICITY",
56        "primary": "RENT_AND_UTILITIES"
57      },
58      "first_date": "2022-02-04",
59      "last_date": "2022-05-02",
60      "frequency": "MONTHLY",
61      "transaction_ids": [
62        "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0",
63        "HPDnUVgI5Pa0YQSl0rxwYRwVXeLyJXTWDAvpR",
64        "jEPoSfF8xzMClE9Ohj1he91QnvYoSdwg7IT8L",
65        "CmdQTNgems8BT1B7ibkoUXVPyAeehT3Tmzk0l"
66      ],
67      "average_amount": {
68        "amount": 85,
69        "iso_currency_code": "USD",
70        "unofficial_currency_code": null
71      },
72      "last_amount": {
73        "amount": 100,
74        "iso_currency_code": "USD",
75        "unofficial_currency_code": null
76      },
77      "is_active": true,
78      "status": "MATURE"
79    },
80    {
81      "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDff",
82      "stream_id": "SrBNJZDuUMweodmPmSOeOImwsWt53ZXfJQAfC",
83      "category": [
84        "Shops",
85        "Warehouses and Wholesale Stores"
86      ],
87      "category_id": "19051000",
88      "description": "Costco Annual Membership",
89      "merchant_name": "Costco",
90      "personal_finance_category": {
91        "detailed": "GENERAL_MERCHANDISE_SUPERSTORES",
92        "primary": "GENERAL_MERCHANDISE"
93      },
94      "first_date": "2022-01-23",
95      "last_date": "2023-01-22",
96      "frequency": "ANNUALLY",
97      "transaction_ids": [
98        "yqEBJ72cS4jFwcpxJcDuQr94oAQ1R1lMC33D4",
99        "Kz5Hm3cZCgpn4tMEKUGAGD6kAcxMBsEZDSwJJ"
100      ],
101      "average_amount": {
102        "amount": 120,
103        "iso_currency_code": "USD",
104        "unofficial_currency_code": null
105      },
106      "last_amount": {
107        "amount": 120,
108        "iso_currency_code": "USD",
109        "unofficial_currency_code": null
110      },
111      "is_active": true,
112      "status": "MATURE"
113    }
114  ],
115  "request_id": "tbFyCEqkU775ZGG"
116}
Was this helpful?

/transactions/refresh

Refresh transaction data

/transactions/refresh is an optional endpoint for users of the Transactions product. It initiates an on-demand extraction to fetch the newest transactions for an Item. This on-demand extraction takes place in addition to the periodic extractions that automatically occur multiple times a day for any Transactions-enabled Item. If changes to transactions are discovered after calling /transactions/refresh, Plaid will fire a webhook: for /transactions/sync users, SYNC_UPDATES_AVAILABLE will be fired if there are any transactions updated, added, or removed. For users of both /transactions/sync and /transactions/get, TRANSACTIONS_REMOVED will be fired if any removed transactions are detected, and DEFAULT_UPDATE will be fired if any new transactions are detected. New transactions can be fetched by calling /transactions/get or /transactions/sync. Note that the /transactions/refresh endpoint is not supported for Capital One (ins_128026) and will result in a PRODUCT_NOT_SUPPORTED error if called on an Item from that institution.
/transactions/refresh is offered as an add-on to Transactions and has a separate fee model. To request access to this endpoint, submit a product access request or contact your Plaid account manager.

transactions/refresh

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
Select group for content switcher
Select Language
1const request: TransactionsRefreshRequest = {
2  access_token: accessToken,
3};
4try {
5  await plaidClient.transactionsRefresh(request);
6} catch (error) {
7  // handle error
8}
transactions/refresh

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "1vwmF5TBQwiqfwP"
3}
Was this helpful?

/categories/get

Get categories

Send a request to the /categories/get endpoint to get detailed information on categories returned by Plaid. This endpoint does not require authentication.
All implementations are recommended to use the newer personal_finance_category taxonomy instead of the older category taxonomy supported by this endpoint. The personal_finance_category taxonomy CSV file is available for download and is not accessible via API.

categories/get

Request fields and example

This endpoint takes an empty request body.
Select group for content switcher
Select Language
1try {
2  const response = await plaidClient.categoriesGet({});
3  const categories = response.data.categories;
4} catch (error) {
5  // handle error
6}
categories/get

Response fields and example

categories
[object]
An array of all of the transaction categories used by Plaid.
category_id
string
An identifying number for the category. category_id is a Plaid-specific identifier and does not necessarily correspond to merchant category codes.
group
string
place for physical transactions or special for other transactions such as bank charges.
hierarchy
[string]
A hierarchical array of the categories to which this category_id belongs.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "categories": [
3    {
4      "category_id": "10000000",
5      "group": "special",
6      "hierarchy": [
7        "Bank Fees"
8      ]
9    },
10    {
11      "category_id": "10001000",
12      "group": "special",
13      "hierarchy": [
14        "Bank Fees",
15        "Overdraft"
16      ]
17    },
18    {
19      "category_id": "12001000",
20      "group": "place",
21      "hierarchy": [
22        "Community",
23        "Animal Shelter"
24      ]
25    }
26  ],
27  "request_id": "ixTBLZGvhD4NnmB"
28}
Was this helpful?

Webhooks

You can receive notifications via a webhook whenever there are new transactions associated with an Item, including when Plaid’s initial and historical transaction pull are completed. All webhooks related to transactions have a webhook_type of TRANSACTIONS.

transactions/refresh

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "1vwmF5TBQwiqfwP"
3}
Was this helpful?

SYNC_UPDATES_AVAILABLE

Fired when an Item's transactions change. This can be due to any event resulting in new changes, such as an initial 30-day transactions fetch upon the initialization of an Item with transactions, the backfill of historical transactions that occurs shortly after, or when changes are populated from a regularly-scheduled transactions update job. It is recommended to listen for the SYNC_UPDATES_AVAILABLE webhook when using the /transactions/sync endpoint. Note that when using /transactions/sync the older webhooks INITIAL_UPDATE, HISTORICAL_UPDATE, DEFAULT_UPDATE, and TRANSACTIONS_REMOVED, which are intended for use with /transactions/get, will also continue to be sent in order to maintain backwards compatibility. It is not necessary to listen for and respond to those webhooks when using /transactions/sync.
After receipt of this webhook, the new changes can be fetched for the Item from /transactions/sync.
Note that to receive this webhook for an Item, /transactions/sync must have been called at least once on that Item. This means that, unlike the INITIAL_UPDATE and HISTORICAL_UPDATE webhooks, it will not fire immediately upon Item creation. If /transactions/sync is called on an Item that was not initialized with Transactions, the webhook will fire twice: once the first 30 days of transactions data has been fetched, and a second time when all available historical transactions data has been fetched.
This webhook will fire in the Sandbox environment as it would in Production. It can also be manually triggered in Sandbox by calling /sandbox/item/fire_webhook.

webhook_type
string
TRANSACTIONS
webhook_code
string
SYNC_UPDATES_AVAILABLE
item_id
string
The item_id of the Item associated with this webhook, warning, or error
initial_update_complete
boolean
Indicates if initial pull information is available.
historical_update_complete
boolean
Indicates if historical pull information is available.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "TRANSACTIONS",
3  "webhook_code": "SYNC_UPDATES_AVAILABLE",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "initial_update_complete": true,
6  "historical_update_complete": false,
7  "environment": "production"
8}
Was this helpful?

RECURRING_TRANSACTIONS_UPDATE

Fired when recurring transactions data is updated. This includes when a new recurring stream is detected or when a new transaction is added to an existing recurring stream. The RECURRING_TRANSACTIONS_UPDATE webhook will also fire when one or more attributes of the recurring stream changes, which is usually a result of the addition, update, or removal of transactions to the stream.
After receipt of this webhook, the updated data can be fetched from /transactions/recurring/get.

webhook_type
string
TRANSACTIONS
webhook_code
string
RECURRING_TRANSACTIONS_UPDATE
item_id
string
The item_id of the Item associated with this webhook, warning, or error
account_ids
[string]
A list of account_ids for accounts that have new or updated recurring transactions data.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "TRANSACTIONS",
3  "webhook_code": "RECURRING_TRANSACTIONS_UPDATE",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "account_ids": [
6    "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
7    "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDff"
8  ],
9  "environment": "production"
10}
Was this helpful?

INITIAL_UPDATE

Fired when an Item's initial transaction pull is completed. Once this webhook has been fired, transaction data for the most recent 30 days can be fetched for the Item. If Account Select v2 is enabled, this webhook will also be fired if account selections for the Item are updated, with new_transactions set to the number of net new transactions pulled after the account selection update.
This webhook is intended for use with /transactions/get; if you are using the newer /transactions/sync endpoint, this webhook will still be fired to maintain backwards compatibility, but it is recommended to listen for and respond to the SYNC_UPDATES_AVAILABLE webhook instead.

webhook_type
string
TRANSACTIONS
webhook_code
string
INITIAL_UPDATE
error
string
The error code associated with the webhook.
new_transactions
number
The number of new, unfetched transactions available.
item_id
string
The item_id of the Item associated with this webhook, warning, or error
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "TRANSACTIONS",
3  "webhook_code": "INITIAL_UPDATE",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "error": null,
6  "new_transactions": 19,
7  "environment": "production"
8}
Was this helpful?

HISTORICAL_UPDATE

Fired when an Item's historical transaction pull is completed and Plaid has prepared as much historical transaction data as possible for the Item. Once this webhook has been fired, transaction data beyond the most recent 30 days can be fetched for the Item. If Account Select v2 is enabled, this webhook will also be fired if account selections for the Item are updated, with new_transactions set to the number of net new transactions pulled after the account selection update.
This webhook is intended for use with /transactions/get; if you are using the newer /transactions/sync endpoint, this webhook will still be fired to maintain backwards compatibility, but it is recommended to listen for and respond to the SYNC_UPDATES_AVAILABLE webhook instead.

webhook_type
string
TRANSACTIONS
webhook_code
string
HISTORICAL_UPDATE
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
new_transactions
number
The number of new, unfetched transactions available
item_id
string
The item_id of the Item associated with this webhook, warning, or error
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "TRANSACTIONS",
3  "webhook_code": "HISTORICAL_UPDATE",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "error": null,
6  "new_transactions": 231,
7  "environment": "production"
8}
Was this helpful?

DEFAULT_UPDATE

Fired when new transaction data is available for an Item. Plaid will typically check for new transaction data several times a day.
This webhook is intended for use with /transactions/get; if you are using the newer /transactions/sync endpoint, this webhook will still be fired to maintain backwards compatibility, but it is recommended to listen for and respond to the SYNC_UPDATES_AVAILABLE webhook instead.

webhook_type
string
TRANSACTIONS
webhook_code
string
DEFAULT_UPDATE
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
new_transactions
number
The number of new transactions detected since the last time this webhook was fired.
item_id
string
The item_id of the Item the webhook relates to.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "TRANSACTIONS",
3  "webhook_code": "DEFAULT_UPDATE",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "error": null,
6  "new_transactions": 3,
7  "environment": "production"
8}
Was this helpful?

TRANSACTIONS_REMOVED

Fired when transaction(s) for an Item are deleted. The deleted transaction IDs are included in the webhook payload. Plaid will typically check for deleted transaction data several times a day.
This webhook is intended for use with /transactions/get; if you are using the newer /transactions/sync endpoint, this webhook will still be fired to maintain backwards compatibility, but it is recommended to listen for and respond to the SYNC_UPDATES_AVAILABLE webhook instead.

webhook_type
string
TRANSACTIONS
webhook_code
string
TRANSACTIONS_REMOVED
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
removed_transactions
[string]
An array of transaction_ids corresponding to the removed transactions
item_id
string
The item_id of the Item associated with this webhook, warning, or error
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "TRANSACTIONS",
3  "webhook_code": "TRANSACTIONS_REMOVED",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "removed_transactions": [
6    "yBVBEwrPyJs8GvR77N7QTxnGg6wG74H7dEDN6",
7    "kgygNvAVPzSX9KkddNdWHaVGRVex1MHm3k9no"
8  ],
9  "error": null,
10  "environment": "production"
11}
Was this helpful?

sandbox user custom

Create Sandbox test data

Use Sandbox accounts to create rich test data for Plaid products

Customize Sandbox account data

In addition to the basic Sandbox credentials, the Sandbox environment also provides the ability to create custom user accounts, which can be used in conjunction with /sandbox/public_token/create or Plaid Link to generate custom Sandbox data, or in conjunction with Plaid Link to test Link flows in the Sandbox.

Using these accounts, you can create your own testing data for the Assets, Auth, Balance, Identity, Investments, Liabilities, and Transactions products. You can also simulate an account with regular income or one that makes regular loan payments. For Link testing, custom accounts support multi-factor authentication, reCAPTCHA, and Link error flows.

Configuring the custom user account

Custom user accounts can be configured and accessed in two ways. The easiest (and recommended) method is by using the Sandbox Users tool, located in the Plaid Dashboard under Developers -> Sandbox. Set the username and configuration object in the Dashboard, then log into the Sandbox with that username and any non-empty password. Alternatively, you can log into Sandbox with the username user_custom and provide the configuration object as the password.

To aid in testing, Plaid maintains a GitHub repo of pre-created custom user accounts that some users have found helpful.

Very large configuration objects (larger than approximately 55kb, or approximately 250 transactions) are not currently supported and may cause the Link attempt to fail.

At OAuth institutions, certain less frequently used customized fields may be overridden by the default values after the Link flow has completed. If this occurs, retry the configuration using a non-OAuth institution.

Configuration object schema

Custom test accounts are configured with a JSON configuration object formulated according to the schema below. All top level fields are optional. Sending an empty object as a configuration will result in an account configured with random balances and transaction history.

version
string
The version of the password schema to use, possible values are 1 or 2. The default value is 2. You should only specify 1 if you know it is necessary for your test suite.
seed
string
A seed, in the form of a string, that will be used to randomly generate account and transaction data, if this data is not specified using the override_accounts argument. If no seed is specified, the randomly generated data will be different each time.
Note that transactions data is generated relative to the Item's creation date. Different Items created on different dates with the same seed for transactions data will have different dates for the transactions. The number of days between each transaction and the Item creation will remain constant. For example, an Item created on December 15 might show a transaction on December 14. An Item created on December 20, using the same seed, would show that same transaction occurring on December 19.
override_accounts
[object]
An array of account overrides to configure the accounts for the Item. By default, if no override is specified, transactions and account data will be randomly generated based on the account type and subtype, and other products will have fixed or empty data.
type
string
investment: Investment account.
credit: Credit card
depository: Depository account
loan: Loan account
payroll: Payroll account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, payroll, other
subtype
string
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
starting_balance
number
If provided, the account will start with this amount as the current balance.

Format: double
force_available_balance
number
If provided, the account will always have this amount as its available balance, regardless of current balance or changes in transactions over time.

Format: double
currency
string
ISO-4217 currency code. If provided, the account will be denominated in the given currency. Transactions will also be in this currency by default.
meta
object
Allows specifying the metadata of the test account
name
string
The account's name
official_name
string
The account's official name
limit
number
The account's limit

Format: double
mask
string
The account's mask. Should be an empty string or a string of 2-4 alphanumeric characters. This allows you to model a mask which does not match the account number (such as with a virtual account number).

Pattern: ^$|^[A-Za-z0-9]{2,4}$
numbers
object
Account and bank identifier number data used to configure the test account. All values are optional.
account
string
Will be used for the account number.
ach_routing
string
Must be a valid ACH routing number.
ach_wire_routing
string
Must be a valid wire transfer routing number.
eft_institution
string
EFT institution number. Must be specified alongside eft_branch.
eft_branch
string
EFT branch number. Must be specified alongside eft_institution.
international_bic
string
Bank identifier code (BIC). Must be specified alongside international_iban.
international_iban
string
International bank account number (IBAN). If no account number is specified via account, will also be used as the account number by default. Must be specified alongside international_bic.
bacs_sort_code
string
BACS sort code
transactions
[object]
Specify the list of transactions on the account.
date_transacted
string
The date of the transaction, in ISO 8601 (YYYY-MM-DD) format. Transactions in Sandbox will move from pending to posted once their transaction date has been reached. If a date_transacted is not provided by the institution, a transaction date may be available in the authorized_date field.

Format: date
date_posted
string
The date the transaction posted, in ISO 8601 (YYYY-MM-DD) format. Posted dates in the past or present will result in posted transactions; posted dates in the future will result in pending transactions.

Format: date
amount
number
The transaction amount. Can be negative.

Format: double
description
string
The transaction description.
currency
string
The ISO-4217 format currency code for the transaction.
holdings
object
Specify the holdings on the account.
institution_price
number
The last price given by the institution for this security

Format: double
institution_price_as_of
string
The date at which institution_price was current. Must be formatted as an ISO 8601 date.

Format: date
cost_basis
number
The average original value of the holding. Multiple cost basis values for the same security purchased at different prices are not supported.

Format: double
quantity
number
The total quantity of the asset held, as reported by the financial institution.

Format: double
currency
string
Either a valid iso_currency_code or unofficial_currency_code
security
object
Specify the security associated with the holding or investment transaction. When inputting custom security data to the Sandbox, Plaid will perform post-data-retrieval normalization and enrichment. These processes may cause the data returned by the Sandbox to be slightly different from the data you input. An ISO-4217 currency code and a security identifier (ticker_symbol, cusip, isin, or sedol) are required.
isin
string
12-character ISIN, a globally unique securities identifier. Please note that Plaid's customers must hold a license directly from CUSIP Global Services to receive CUSIP & ISIN data. This field will be null by default for new customers. For existing customers, this field will be null by default starting on Sept 15, 2023. If you would like access to this field, please contact your Plaid Account Manager or reach out to investments-vendors@plaid.com.
cusip
string
9-character CUSIP, an identifier assigned to North American securities. Please note that Plaid's customers must hold a license directly from CUSIP Global Services to receive CUSIP & ISIN data. This field will be null by default for new customers. For existing customers, this field will be null by default starting on Sept 15, 2023. If you would like access to this field, please contact your Plaid Account Manager or reach out to investments-vendors@plaid.com.
sedol
string
7-character SEDOL, an identifier assigned to securities in the UK.
name
string
A descriptive name for the security, suitable for display.
ticker_symbol
string
The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available.
currency
string
Either a valid iso_currency_code or unofficial_currency_code
investment_transactions
object
Specify the list of investments transactions on the account.
date
string
Posting date for the transaction. Must be formatted as an ISO 8601 date.

Format: date
name
string
The institution's description of the transaction.
quantity
number
The number of units of the security involved in this transaction. Must be positive if the type is a buy and negative if the type is a sell.

Format: double
price
number
The price of the security at which this transaction occurred.

Format: double
fees
number
The combined value of all fees applied to this transaction.

Format: double
type
string
The type of the investment transaction. Possible values are: buy: Buying an investment sell: Selling an investment cash: Activity that modifies a cash position fee: A fee on the account transfer: Activity that modifies a position, but not through buy/sell activity e.g. options exercise, portfolio transfer
currency
string
Either a valid iso_currency_code or unofficial_currency_code
security
object
Specify the security associated with the holding or investment transaction. When inputting custom security data to the Sandbox, Plaid will perform post-data-retrieval normalization and enrichment. These processes may cause the data returned by the Sandbox to be slightly different from the data you input. An ISO-4217 currency code and a security identifier (ticker_symbol, cusip, isin, or sedol) are required.
isin
string
12-character ISIN, a globally unique securities identifier. Please note that Plaid's customers must hold a license directly from CUSIP Global Services to receive CUSIP & ISIN data. This field will be null by default for new customers. For existing customers, this field will be null by default starting on Sept 15, 2023. If you would like access to this field, please contact your Plaid Account Manager or reach out to investments-vendors@plaid.com.
cusip
string
9-character CUSIP, an identifier assigned to North American securities. Please note that Plaid's customers must hold a license directly from CUSIP Global Services to receive CUSIP & ISIN data. This field will be null by default for new customers. For existing customers, this field will be null by default starting on Sept 15, 2023. If you would like access to this field, please contact your Plaid Account Manager or reach out to investments-vendors@plaid.com.
sedol
string
7-character SEDOL, an identifier assigned to securities in the UK.
name
string
A descriptive name for the security, suitable for display.
ticker_symbol
string
The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available.
currency
string
Either a valid iso_currency_code or unofficial_currency_code
identity
object
Data about the owner or owners of an account. Any fields not specified will be filled in with default Sandbox information.
names
[string]
A list of names associated with the account by the financial institution. These should always be the names of individuals, even for business accounts. Note that the same name data will be used for all accounts associated with an Item.
phone_numbers
[object]
A list of phone numbers associated with the account.
data
string
The phone number.
primary
boolean
When true, identifies the phone number as the primary number on an account.
type
string
The type of phone number.

Possible values: home, work, office, mobile, mobile1, other
emails
[object]
A list of email addresses associated with the account.
data
string
The email address.
primary
boolean
When true, identifies the email address as the primary email on an account.
type
string
The type of email account as described by the financial institution.

Possible values: primary, secondary, other
addresses
[object]
Data about the various addresses associated with the account.
data
object
Data about the components comprising an address.
city
string
The full city name
region
string
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
string
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
string
The ISO 3166-1 alpha-2 country code
primary
boolean
When true, identifies the address as the primary address on an account.
liability
object
Used to configure Sandbox test data for the Liabilities product
type
string
The type of the liability object, either credit or student. Mortgages are not currently supported in the custom Sandbox.
purchase_apr
number
The purchase APR percentage value. For simplicity, this is the only interest rate used to calculate interest charges. Can only be set if type is credit.

Format: double
cash_apr
number
The cash APR percentage value. Can only be set if type is credit.

Format: double
balance_transfer_apr
number
The balance transfer APR percentage value. Can only be set if type is credit.

Format: double
special_apr
number
The special APR percentage value. Can only be set if type is credit.

Format: double
last_payment_amount
number
Override the last_payment_amount field. Can only be set if type is credit.

Format: double
minimum_payment_amount
number
Override the minimum_payment_amount field. Can only be set if type is credit or student.

Format: double
is_overdue
boolean
Override the is_overdue field
origination_date
string
The date on which the loan was initially lent, in ISO 8601 (YYYY-MM-DD) format. Can only be set if type is student.

Format: date
principal
number
The original loan principal. Can only be set if type is student.

Format: double
nominal_apr
number
The interest rate on the loan as a percentage. Can only be set if type is student.

Format: double
interest_capitalization_grace_period_months
number
If set, interest capitalization begins at the given number of months after loan origination. By default interest is never capitalized. Can only be set if type is student.
repayment_model
object
Student loan repayment information used to configure Sandbox test data for the Liabilities product
type
string
The only currently supported value for this field is standard.
non_repayment_months
number
Configures the number of months before repayment starts.
repayment_months
number
Configures the number of months of repayments before the loan is paid off.
expected_payoff_date
string
Override the expected_payoff_date field. Can only be set if type is student.

Format: date
guarantor
string
Override the guarantor field. Can only be set if type is student.
is_federal
boolean
Override the is_federal field. Can only be set if type is student.
loan_name
string
Override the loan_name field. Can only be set if type is student.
loan_status
object
An object representing the status of the student loan
end_date
string
The date until which the loan will be in its current status. Dates are returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
type
string
The status type of the student loan

Possible values: cancelled, charged off, claim, consolidated, deferment, delinquent, discharged, extension, forbearance, in grace, in military, in school, not fully disbursed, other, paid in full, refunded, repayment, transferred
payment_reference_number
string
Override the payment_reference_number field. Can only be set if type is student.
pslf_status
object
Information about the student's eligibility in the Public Service Loan Forgiveness program. This is only returned if the institution is FedLoan (ins_116527).
estimated_eligibility_date
string
The estimated date borrower will have completed 120 qualifying monthly payments. Returned in ISO 8601 format (YYYY-MM-DD).

Format: date
payments_made
integer
The number of qualifying payments that have been made.
payments_remaining
integer
The number of qualifying payments remaining.
repayment_plan_description
string
Override the repayment_plan.description field. Can only be set if type is student.
repayment_plan_type
string
Override the repayment_plan.type field. Can only be set if type is student. Possible values are: "extended graduated", "extended standard", "graduated", "income-contingent repayment", "income-based repayment", "interest only", "other", "pay as you earn", "revised pay as you earn", or "standard".
sequence_number
string
Override the sequence_number field. Can only be set if type is student.
servicer_address
object
A physical mailing address.
data
object
Data about the components comprising an address.
city
string
The full city name
region
string
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
string
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
string
The ISO 3166-1 alpha-2 country code
primary
boolean
When true, identifies the address as the primary address on an account.
inflow_model
object
The inflow_model allows you to model a test account that receives regular income or make regular payments on a loan. Any transactions generated by the inflow_model will appear in addition to randomly generated test data or transactions specified by override_accounts.
type
string
Inflow model. One of the following:
none: No income
monthly-income: Income occurs once per month monthly-balance-payment: Pays off the balance on a liability account at the given statement day of month.
monthly-interest-only-payment: Makes an interest-only payment on a liability account at the given statement day of month.
Note that account types supported by Liabilities will accrue interest in the Sandbox. The types impacted are account type credit with subtype credit or paypal, and account type loan with subtype student or mortgage.
income_amount
number
Amount of income per month. This value is required if type is monthly-income.

Format: double
payment_day_of_month
number
Number between 1 and 28, or last meaning the last day of the month. The day of the month on which the income transaction will appear. The name of the income transaction. This field is required if type is monthly-income, monthly-balance-payment or monthly-interest-only-payment.
transaction_name
string
The name of the income transaction. This field is required if type is monthly-income, monthly-balance-payment or monthly-interest-only-payment.
statement_day_of_month
string
Number between 1 and 28, or last meaning the last day of the month. The day of the month on which the balance is calculated for the next payment. The name of the income transaction. This field is required if type is monthly-balance-payment or monthly-interest-only-payment.
income
object
Specify payroll data on the account.
paystubs
[object]
A list of paystubs associated with the account.
employer
object
The employer on the paystub.
name
string
The name of the employer.
employee
object
The employee on the paystub.
name
string
The name of the employee.
address
object
The address of the employee.
city
string
The full city name.
region
string
The region or state Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
string
5 digit postal code.
country
string
The country of the address.
income_breakdown
[object]
type
string
The type of income. Possible values include: "regular": regular income "overtime": overtime income "bonus": bonus income

Possible values: bonus, overtime, regular, null
rate
number
The hourly rate at which the income is paid.

Format: double
hours
number
The number of hours logged for this income for this pay period.
total
number
The total pay for this pay period.

Format: double
pay_period_details
object
Details about the pay period.
check_amount
number
The amount of the paycheck.

Format: double
distribution_breakdown
[object]
account_name
string
Name of the account for the given distribution.
bank_name
string
The name of the bank that the payment is being deposited to.
current_amount
number
The amount distributed to this account.

Format: double
iso_currency_code
string
The ISO-4217 currency code of the net pay. Always null if unofficial_currency_code is non-null.
mask
string
The last 2-4 alphanumeric characters of an account's official account number.
type
string
Type of the account that the paystub was sent to (e.g. 'checking').
unofficial_currency_code
string
The unofficial currency code associated with the net pay. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
current_pay
deprecatedobject
An object representing a monetary amount.
amount
number
A numerical amount of a specific currency.

Format: double
currency
string
Currency code, e.g. USD
end_date
string
The pay period end date, in ISO 8601 format: "yyyy-mm-dd".

Format: date
gross_earnings
number
Total earnings before tax/deductions.

Format: double
pay_date
string
The date on which the paystub was issued, in ISO 8601 format ("yyyy-mm-dd").

Format: date
pay_frequency
string
The frequency at which an individual is paid.

Possible values: PAY_FREQUENCY_UNKNOWN, PAY_FREQUENCY_WEEKLY, PAY_FREQUENCY_BIWEEKLY, PAY_FREQUENCY_SEMIMONTHLY, PAY_FREQUENCY_MONTHLY, null
pay_day
deprecatedstring
The date on which the paystub was issued, in ISO 8601 format ("yyyy-mm-dd").

Format: date
start_date
string
The pay period start date, in ISO 8601 format: "yyyy-mm-dd".

Format: date
mfa
object
Specifies the multi-factor authentication settings to use with this test account
type
string
Possible values are device, selections, or questions.
If value is device, the MFA answer is 1234.
If value is selections, the MFA answer is always the first option.
If value is questions, the MFA answer is answer_<i>_<j> for the j-th question in the i-th round, starting from 0. For example, the answer to the first question in the second round is answer_1_0.
question_rounds
number
Number of rounds of questions. Required if value of type is questions.
questions_per_round
number
Number of questions per round. Required if value of type is questions. If value of type is selections, default value is 2.
selection_rounds
number
Number of rounds of selections, used if type is selections. Defaults to 1.
selections_per_question
number
Number of available answers per question, used if type is selection. Defaults to 2.
recaptcha
string
You may trigger a reCAPTCHA in Plaid Link in the Sandbox environment by using the recaptcha field. Possible values are good or bad. A value of good will result in successful Item creation and bad will result in a RECAPTCHA_BAD error to simulate a failed reCAPTCHA. Both values require the reCAPTCHA to be manually solved within Plaid Link.
force_error
string
An error code to force on Item creation. Possible values are:
"INSTITUTION_NOT_RESPONDING" "INSTITUTION_NO_LONGER_SUPPORTED" "INVALID_CREDENTIALS" "INVALID_MFA" "ITEM_LOCKED" "ITEM_LOGIN_REQUIRED" "ITEM_NOT_SUPPORTED" "INVALID_LINK_TOKEN" "MFA_NOT_SUPPORTED" "NO_ACCOUNTS" "PLAID_ERROR" "USER_INPUT_TIMEOUT" "USER_SETUP_REQUIRED"
1{
2  "seed": "my-seed-string-3",
3  "override_accounts": [
4    {
5      "type": "depository",
6      "subtype": "checking",
7      "identity": {
8        "names": [
9          "John Doe"
10        ],
11        "phone_numbers": [
12          {
13            "primary": true,
14            "type": "home",
15            "data": "4673956022"
16          }
17        ],
18        "emails": [
19          {
20            "primary": true,
21            "type": "primary",
22            "data": "accountholder0@example.com"
23          }
24        ],
25        "addresses": [
26          {
27            "primary": true,
28            "data": {
29              "city": "Malakoff",
30              "region": "NY",
31              "street": "2992 Cameron Road",
32              "postal_code": "14236",
33              "country": "US"
34            }
35          }
36        ]
37      },
38      "transactions": [
39        {
40          "date_transacted": "2019-10-01",
41          "date_posted": "2019-10-03",
42          "currency": "USD",
43          "amount": 100,
44          "description": "1 year Netflix subscription"
45        },
46        {
47          "date_transacted": "2019-10-01",
48          "date_posted": "2019-10-02",
49          "currency": "USD",
50          "amount": 100,
51          "description": "1 year mobile subscription"
52        }
53      ]
54    },
55    {
56      "type": "loan",
57      "subtype": "student",
58      "liability": {
59        "type": "student",
60        "origination_date": "2020-01-01",
61        "principal": 10000,
62        "nominal_apr": 6.25,
63        "loan_name": "Plaid Student Loan",
64        "repayment_model": {
65          "type": "standard",
66          "non_repayment_months": 12,
67          "repayment_months": 120
68        }
69      }
70    },
71    {
72      "type": "credit",
73      "subtype": "credit card",
74      "starting_balance": 10000,
75      "inflow_model": {
76        "type": "monthly-interest-only-payment",
77        "payment_day_of_month": 15,
78        "statement_day_of_month": 13,
79        "transaction_name": "Interest Payment"
80      },
81      "liability": {
82        "type": "credit",
83        "purchase_apr": 12.9,
84        "balance_transfer_apr": 15.24,
85        "cash_apr": 28.45,
86        "special_apr": 0,
87        "last_payment_amount": 500,
88        "minimum_payment_amount": 10
89      }
90    },
91    {
92      "type": "investment",
93      "subtype": "brokerage",
94      "investment_transactions": [
95        {
96          "date": "2021-07-01",
97          "name": "buy stock",
98          "quantity": 10,
99          "price": 10,
100          "fees": 20,
101          "type": "buy",
102          "currency": "USD",
103          "security": {
104            "ticker_symbol": "PLAID",
105            "currency": "USD"
106          }
107        }
108      ],
109      "holdings": [
110        {
111          "institution_price": 10,
112          "institution_price_as_of": "2021-08-01",
113          "cost_basis": 10,
114          "quantity": 10,
115          "currency": "USD",
116          "security": {
117            "ticker_symbol": "PLAID",
118            "currency": "USD"
119          }
120        }
121      ]
122    },
123    {
124      "type": "payroll",
125      "subtype": "payroll",
126      "income": {
127        "paystubs": [
128          {
129            "employer": {
130              "name": "Heartland Toy Company"
131            },
132            "employee": {
133              "name": "Chip Hazard",
134              "address": {
135                "city": "Burbank",
136                "region": "CA",
137                "street": "411 N Hollywood Way",
138                "postal_code": "91505",
139                "country": "US"
140              }
141            },
142            "income_breakdown": [
143              {
144                "type": "regular",
145                "rate": 20,
146                "hours": 40,
147                "total": 800
148              },
149              {
150                "type": "overtime",
151                "rate": 30,
152                "hours": 6.68,
153                "total": 200.39
154              }
155            ],
156            "pay_period_details": {
157              "start_date": "2021-05-04",
158              "end_date": "2021-05-18",
159              "gross_earnings": 1000.39,
160              "check_amount": 499.28
161            }
162          }
163        ]
164      }
165    }
166  ]
167}
Was this helpful?

link duplicate items

Preventing duplicate Items

Prevent unnecessary billing and confusing application behavior

Prefer to learn by watching? A video guide is available for this topic.

How duplicate Items are created

An Item represents a login at a financial institution. This login typically happens when an end user links an account (or several accounts) using Plaid Link. A duplicate Item will be created if the end user logs into the same institution using the same credentials again using Plaid Link (in the same application), and if an access token is requested for the Item.

Duplicate Items can occur for multiple reasons. For example, a duplicate Item can occur if a user accidentally links the same account more than once, because they do not realize they already linked an account, or because their linked account is no longer working. Duplicate Items can also occur if a user intentionally links multiple Items for abusive purposes (for example, as part of an attempt to receive multiple sign-up bonuses or to evade a ban).

Duplicate Items can create confusing or unwanted behavior in your application and could result in being potentially billed for multiple Items. We recommend building safeguards in your application to help prevent end users from creating duplicate Items. In this article, we'll describe a few ways to prevent and detect Item duplication.

Preventing duplicate Items

Use the onSuccess callback metadata

The onSuccess callback is called when a user successfully links an Item using Plaid Link. This callback provides metadata that you can use to prevent duplicate Items from being created. One approach is to require a user login prior to launching Plaid Link so that you can retrieve existing Items associated with the user.

Then, before requesting an access_token, examine and compare the onSuccess callback metadata to the user's existing Items. You can compare a combination of the accounts’ institution_id, account name, and account mask to determine whether an end user has previously linked an account to your application. Do not exchange a public token for an access token if you detect a duplicate Item.

While the mask value is usually the same as the last 4 digits of the account number, this is not the case at all institutions. Never detect duplicate Items by attempting to match a mask with an account number.

1{
2  institution: {
3    name: 'Wells Fargo',
4    institution_id: 'ins_4'
5  },
6  accounts: [
7    {
8      id: 'ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy',
9      name: 'Plaid Checking',
10      mask: '0000',
11      type: 'depository',
12      subtype: 'checking',
13      verification_status: ''
14    },
15    {
16      id: '9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4',
17      name: 'Plaid Saving',
18      mask: '1111',
19      type: 'depository',
20      subtype: 'savings'
21    }
22    ...
23  ],
24  link_session_id: '79e772be-547d-4c9c-8b76-4ac4ed4c441a'
25}

For Items linked via OAuth or Account Selection v2, note that duplicate Items are not always identical. For example, an Item may have a checking account linked, while its duplicate may have only a savings account linked. While this scenario is rare, if it becomes a problem for your use case, you can switch to using the institution_id field on a per-user basis to prevent duplicate Items and enforce that each user of your app not link multiple Items with the same institution. However, because this is a legitimate use case for some applications, it is not recommended as the primary means of detecting duplicate Items.

Duplicate Items with certain OAuth institutions

For some institutions that use OAuth connections, including Chase and Charles Schwab, existing Items will be invalidated if an end user adds a second Item using the same credentials, at the point when the onSuccess callback is returned. For this reason, the onSuccess metadata approach cannot be used to prevent duplicate Items at these institutions. Instead, use alternative means of preventing duplicate Items, described below. If a duplicate Item is created, delete the old Item using /item/remove.

Implement Pre-Link messaging

A lightweight but effective method for preventing accidental duplicate Items from being created is by providing relevant messaging and information to end users before they engage with Plaid Link in your application. For example, displaying a list of accounts they've already connected to your application can help prevent end users from inadvertently linking the same accounts again.

Use Link's update mode

From time to time, an Item may become unhealthy due to entering the ITEM_LOGIN_REQUIRED state. Or, the Item may still be healthy, but you may want your end user to authorize additional accounts or permissions associated with the Item. When either of these scenarios happens, use Link in update mode to refresh the Item instead of creating a new Item.

Example implementation: Preventing accidental duplicate Items

For an example that demonstrates how to prevent accidental duplicate Items, see the Plaid Pattern sample app. Plaid Pattern implements simple server-side logic to check whether the user ID and institution ID pair already exist in the application database. If the pair exists, an access token will not be requested for this Item, thereby preventing a duplicate. In addition, a message is displayed to the end user informing them that they've already linked this Item. The relevant code can be found in /server/routes/items.js and /server/db/queries/items.js.

Identifying existing duplicate Items

To identify existing duplicate Items, use the same matching logic as described above, but retrieve this data via the /accounts/get endpoint instead of the onSuccess callback. Occasionally, the mask or name fields may be null, in which case you can compare institution_id and client_user_id as a fallback. After identifying duplicate Items, use the /item/remove endpoint to delete an Item.

If you are using Auth via /auth/get, existing duplicate Items may be detected by using the account and routing number fields and looking for duplicates. Note that this method will not work for Chase Items, as Chase uses tokenized account numbers. If you wish to detect existing duplicate Items at Chase, you can use the persistent_account_id field, which will be the same across duplicate instances of a Chase Item. This field is in beta; to request access, contact Support or your Account Manager.

Detecting and preventing duplicate Items across user accounts

When attempting to detect or prevent duplicate Items, your approach should depend on the type of duplicate Item you are trying to prevent. For example, you can often scope your search to either a single user's accounts, or to all accounts known to your application. If you are attempting to prevent accidental duplicate Items, you should scope the search to a single user; if you are attempting to detect or prevent abuse, it may make more sense to expand your search to all accounts that have been linked to your app.

Note that there can be legitimate use cases for the same financial institution account to be linked across multiple different user accounts (for example, family members who share a joint bank account, or employees of the same company who share access to a business account); depending on your use case, you may want to incorporate this data into a broader abuse detection framework rather than blocking all duplicate accounts.

link institution status

Institution status in Link

Details of institution health status accessible in Link

Institution status in Link

Link proactively lets users know if an institution's connection isn't performing well. Below are the three views a user will see depending on the status of the institution they select.

When the status of item_logins of an institution is DEGRADED, Link will warn users that they may experience issues and allow them to continue. Once the status of item_logins becomes DOWN, Link will block users from attempting to log in and suggest they find another bank.

Screenshot of Link institution status health panes

Institution Health warnings can be tested in the Sandbox environment by using one of the dedicated "Unhealthy" Platypus Bank test institutions.

For a more detailed view of institution status, see the status dashboard, which provides a browsable view of institutions, supported products, and institution health.

Connectivity not supported

Screenshot of Link connectivity not supported pane

If an institution is supported by Plaid, but is not supported by the product set Link was initialized with, a "Connectivity not supported" error message will appear. This message does not reflect the health of the institution. This message can be resolved by calling /link/token/create with a more minimal product set. For more details, see Link troubleshooting.

api products enrich

Enrich

API reference for Enrich endpoint

Endpoints
/transactions/enrichSend transaction data and retrieve enrichments

/transactions/enrich

Enrich locally-held transaction data

The /transactions/enrich endpoint enriches raw transaction data generated by your own banking products or retrieved from other non-Plaid sources.

transactions/enrich

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
account_type
requiredstring
The account type for the requested transactions (either depository or credit).
transactions
required[object]
An array of transaction objects to be enriched by Plaid. Maximum of 100 transactions per request.
id
requiredstring
A unique ID for the transaction used to help you tie data back to your systems.
description
requiredstring
The raw description of the transaction. If you have location data in available an unstructured format, it may be appended to the description field.
amount
requirednumber
The absolute value of the transaction (>= 0). When testing Enrich, note that amount data should be realistic. Unrealistic or inaccurate amount data may result in reduced quality output.

Format: double
direction
requiredstring
The direction of the transaction from the perspective of the account holder:
OUTFLOW - Includes outgoing transfers, purchases, and fees. (Typically represented as a negative value on checking accounts and debit cards and a positive value on credit cards.)
INFLOW - Includes incoming transfers, refunds, and income. (Typically represented as a positive value on checking accounts and debit cards and a negative value on credit cards.)

Possible values: INFLOW, OUTFLOW
iso_currency_code
requiredstring
The ISO-4217 currency code of the transaction e.g. USD.
location
object
A representation of where a transaction took place.
Use this field to pass in structured location information you may have about your transactions. Providing location data is optional but can increase result quality. If you have unstructured location information, it may be appended to the description field.
country
string
The country where the transaction occurred.
region
string
The region or state where the transaction occurred.
city
string
The city where the transaction occurred.
address
string
The street address where the transaction occurred.
postal_code
string
The postal code where the transaction occurred.
mcc
string
Merchant category codes (MCCs) are four-digit numbers that describe a merchant's primary business activities.
date_posted
string
The date the transaction posted, in ISO 8601 (YYYY-MM-DD) format.

Format: date
options
object
An optional object to be used with the request.
include_legacy_category
boolean
Include legacy_category and legacy_category_id in the response (in addition to the default personal_finance_category).
Categories are based on Plaid's legacy taxonomy. For a full list of legacy categories, see /categories/get.

Default: false
Select Language
1const transactionsToEnrich: Array<ClientProvidedTransaction> = [
2  {
3    id: "1",
4    description: "PURCHASE WM SUPERCENTER #1700",
5    amount: 72.10,
6    iso_currency_code: "USD",
7    location: {
8      city: "Poway",
9      region: "CA",
10    },
11    direction: EnrichTransactionDirection.Outflow,
12  },
13  {
14    id: "2",
15    description: "DD DOORDASH BURGERKIN 855-123-4567 CA",
16    amount: 28.34,
17    iso_currency_code: "USD",
18    direction: EnrichTransactionDirection.Outflow
19  }
20];
21
22const request: TransactionsEnrichGetRequest = {
23  account_type: "depository",
24  transactions: transactionsToEnrich
25};
26
27const response = await client.transactionsEnrich(request);
28const enrichedTransactions = response.data.enriched_transactions;
transactions/enrich

Response fields and example

enriched_transactions
[object]
A list of enriched transactions.
id
string
The unique ID for the transaction as provided by you in the request.
description
string
The raw description of the transaction.
amount
number
The absolute value of the transaction (>= 0)

Format: double
direction
string
The direction of the transaction from the perspective of the account holder:
OUTFLOW - Includes outgoing transfers, purchases, and fees. (Typically represented as a negative value on checking accounts and debit cards and a positive value on credit cards.)
INFLOW - Includes incoming transfers, refunds, and income. (Typically represented as a positive value on checking accounts and debit cards and a negative value on credit cards.)

Possible values: INFLOW, OUTFLOW
iso_currency_code
string
The ISO-4217 currency code of the transaction e.g. USD.
enrichments
object
A grouping of the Plaid produced transaction enrichment fields.
counterparties
[object]
The counterparties present in the transaction. Counterparties, such as the merchant or the financial institution, are extracted by Plaid from the raw description.
name
string
The name of the counterparty, such as the merchant or the financial institution, as extracted by Plaid from the raw description.
entity_id
nullablestring
A unique, stable, Plaid-generated id that maps to the counterparty.
type
string
The counterparty type.
merchant: a provider of goods or services for purchase financial_institution: a financial entity (bank, credit union, BNPL, fintech) payment_app: a transfer or P2P app (e.g. Zelle) marketplace: a marketplace (e.g DoorDash, Google Play Store) payment_terminal: a point-of-sale payment terminal (e.g Square, Toast) income_source: the payer in an income transaction (e.g., an employer, client, or government agency)

Possible values: merchant, financial_institution, payment_app, marketplace, payment_terminal, income_source
website
nullablestring
The website associated with the counterparty.
logo_url
nullablestring
The URL of a logo associated with the counterparty, if available. The logo is formatted as a 100x100 pixel PNG file.
confidence_level
nullablestring
A description of how confident we are that the provided counterparty is involved in the transaction.
VERY_HIGH: We recognize this counterparty and we are more than 98% confident that it is involved in this transaction. HIGH: We recognize this counterparty and we are more than 90% confident that it is involved in this transaction. MEDIUM: We are moderately confident that this counterparty was involved in this transaction, but some details may differ from our records. LOW: We didn’t find a matching counterparty in our records, so we are returning a cleansed name parsed out of the request description. UNKNOWN: Error
entity_id
nullablestring
A unique, stable, Plaid-generated id that maps to the primary counterparty.
legacy_category_id
deprecatednullablestring
The ID of the legacy category to which this transaction belongs. For a full list of legacy categories, see /categories/get.
We recommend using the personal_finance_category for transaction categorization to obtain the best results.
legacy_category
deprecated[string]
A hierarchical array of the legacy categories to which this transaction belongs. For a full list of legacy categories, see /categories/get.
We recommend using the personal_finance_category for transaction categorization to obtain the best results.
location
object
A representation of where a transaction took place
address
nullablestring
The street address where the transaction occurred.
city
nullablestring
The city where the transaction occurred.
region
nullablestring
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.
postal_code
nullablestring
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code where the transaction occurred.
lat
nullablenumber
The latitude where the transaction occurred.

Format: double
lon
nullablenumber
The longitude where the transaction occurred.

Format: double
store_number
nullablestring
The merchant defined store number where the transaction occurred.
logo_url
nullablestring
The URL of a logo associated with this transaction, if available. The logo is formatted as a 100x100 pixel PNG file.
merchant_name
nullablestring
The name of the primary counterparty, such as the merchant or the financial institution, as extracted by Plaid from the raw description.
payment_channel
string
The channel used to make a payment. online: transactions that took place online.
in store: transactions that were made at a physical location.
other: transactions that relate to banks, e.g. fees or deposits.

Possible values: online, in store, other
personal_finance_category
nullableobject
Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases.
See the taxonomy csv file for a full list of personal finance categories.
primary
string
A high level category that communicates the broad category of the transaction.
detailed
string
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.
confidence_level
nullablestring
Note: This field is only available for /transactions/enrich endpoint currently. A description of how confident we are that the provided categories accurately describe the transaction intent.
VERY_HIGH: We are more than 98% confident that this category reflects the intent of the transaction. HIGH: We are more than 90% confident that this category reflects the intent of the transaction. MEDIUM: We are moderately confident that this category reflects the intent of the transaction. LOW: This category may reflect the intent, but there may be other categories that are more accurate. UNKNOWN: Error
personal_finance_category_icon_url
string
A link to the icon associated with the primary personal finance category. The logo will always be 100x100 pixels.
recurrence
nullableobject
Insights relating to expenses and deposits that are predicted to occur on a scheduled basis, such as biweekly, monthly, or annually.
Common examples include loan payments, bill payments, subscriptions, and payroll income.
This is a beta field, available to all users.
is_recurring
nullableboolean
Whether or not the transaction is periodically recurring.
website
nullablestring
The website associated with this transaction.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "enriched_transactions": [
3    {
4      "id": "6135818adda16500147e7c1d",
5      "description": "PURCHASE WM SUPERCENTER #1700",
6      "amount": 72.1,
7      "direction": "OUTFLOW",
8      "iso_currency_code": "USD",
9      "enrichments": {
10        "counterparties": [
11          {
12            "name": "Walmart",
13            "type": "merchant",
14            "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",
15            "website": "walmart.com",
16            "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM",
17            "confidence_level": "VERY_HIGH"
18          }
19        ],
20        "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM",
21        "location": {
22          "address": "13425 Community Rd",
23          "city": "Poway",
24          "region": "CA",
25          "postal_code": "92064",
26          "country": "US",
27          "store_number": "1700",
28          "lat": 32.959068,
29          "lon": -117.037666
30        },
31        "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",
32        "merchant_name": "Walmart",
33        "payment_channel": "in store",
34        "personal_finance_category": {
35          "detailed": "GENERAL_MERCHANDISE_SUPERSTORES",
36          "primary": "GENERAL_MERCHANDISE",
37          "confidence_level": "VERY_HIGH"
38        },
39        "recurrence": {
40          "is_recurring": false
41        },
42        "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png",
43        "website": "walmart.com"
44      }
45    },
46    {
47      "id": "3958434bhde9384bcmeo3401",
48      "description": "DD DOORDASH BURGERKIN 855-123-4567 CA",
49      "amount": 28.34,
50      "direction": "OUTFLOW",
51      "iso_currency_code": "USD",
52      "enrichments": {
53        "counterparties": [
54          {
55            "name": "DoorDash",
56            "type": "marketplace",
57            "logo_url": "https://plaid-counterparty-logos.plaid.com/doordash_1.png",
58            "website": "doordash.com",
59            "entity_id": "YNRJg5o2djJLv52nBA1Yn1KpL858egYVo4dpm",
60            "confidence_level": "VERY_HIGH"
61          },
62          {
63            "name": "Burger King",
64            "type": "merchant",
65            "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png",
66            "website": "burgerking.com",
67            "entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1",
68            "confidence_level": "VERY_HIGH"
69          }
70        ],
71        "location": {
72          "address": null,
73          "city": null,
74          "region": null,
75          "postal_code": null,
76          "country": null,
77          "store_number": null,
78          "lat": null,
79          "lon": null
80        },
81        "entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1",
82        "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png",
83        "merchant_name": "Burger King",
84        "payment_channel": "online",
85        "personal_finance_category": {
86          "detailed": "FOOD_AND_DRINK_FAST_FOOD",
87          "primary": "FOOD_AND_DRINK",
88          "confidence_level": "VERY_HIGH"
89        },
90        "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_FOOD_AND_DRINK.png",
91        "recurrence": {
92          "is_recurring": false
93        },
94        "website": "burgerking.com"
95      }
96    }
97  ],
98  "request_id": "Wvhy9PZHQLV8njG"
99}
Was this helpful?

auth add to app

Add Auth to your app

Use Auth to connect user bank accounts

In this guide, we'll demonstrate how to add Auth to your app so that you can connect to your users' bank accounts and obtain the information needed to set up funds transfers.

If you're already familiar with using Plaid and are set up to make calls to the Plaid API, see Getting Auth data. If you're interested in using a Plaid partner, such as Stripe or Dwolla, to process payments, see Moving funds with a payment partner.

Prefer to learn by watching? A video guide is available for this topic.

Get Plaid API keys and complete application and company profile

If you don't already have one, you'll need to create a Plaid developer account. After creating your account, you can find your API keys under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your application profile and company profile in the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the Plaid Portal. Your application profile and company profile must be completed before connecting to certain institutions in Production.

Install and initialize Plaid libraries

You can use our official server-side client libraries to connect to the Plaid API from your application:

Select group for content switcher
Select Language
1// Install via npm
2npm install --save plaid

After you've installed Plaid's client libraries, you can initialize them by passing in your client_id, secret, and the environment you wish to connect to (Sandbox, Development, or Production). This will make sure the client libraries pass along your client_id and secret with each request, and you won't need to explicitly include them in any other calls.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can obtain from the Dashboard. These code samples also demonstrate starting up a server commonly used in each framework (such as Express or Flask).

Select group for content switcher
Select Language
1// Using Express
2const express = require('express');
3const app = express();
4app.use(express.json());
5
6const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
7
8const configuration = new Configuration({
9  basePath: PlaidEnvironments.sandbox,
10  baseOptions: {
11    headers: {
12      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
13      'PLAID-SECRET': process.env.PLAID_SECRET,
14    },
15  },
16});
17
18const client = new PlaidApi(configuration);

Create an Item using Link

These instructions cover Link for web applications. For instructions on using Link in mobile apps, see the Link documentation.

Plaid Link is the client-side component that your users interact with to securely connect their bank accounts to your app. An Item is created when a user successfully logs into their financial institution using Link. An Item represents a single login at a financial institution. Items do not represent individual bank accounts, although all bank accounts are associated with an Item. For example, if a user has a single login at a bank that allows them to access both a checking account and a savings account, only a single Item would be associated with both of the accounts.

When using Auth, you will typically only need access to the specific bank account that will be used to transfer funds, rather than all of the accounts a user may have at an institution. Because of this, it is recommended that you configure Link with Account Select when using Auth. Configuring Link with Account Select will limit unnecessary access to user accounts. You can enable Account Select from the Dashboard.

To create an Item, you'll first need to create a Link token on your application server. You can create a Link token by calling the /link/token/create endpoint. Then, on the client-side of your application, you'll initialize Link with using the Link token you created.

The code samples below demonstrate how to create a Link token and how to initialize Link using the token.

Create a Link token
Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Initialize Link with the Link token
1const handler = Plaid.create({
2  token: (await $.post('/create_link_token')).link_token,
3  onSuccess: (public_token, metadata) => {
4    // Upon successful linking of a bank account,
5    // Link will return a public token.
6    // Exchange the public token for an access token
7    // to make calls to the Plaid API.
8    $.post('/exchange_public_token', {
9      public_token: public_token,
10    });
11  },
12  onLoad: () => {},
13  onExit: (err, metadata) => {
14    // Optionally capture when your user exited the Link flow.
15    // Storing this information can be helpful for support.
16  },
17  onEvent: (eventName, metadata) => {
18    // Optionally capture Link flow events, streamed through
19    // this callback as your users connect an Item to Plaid.
20  },
21  //required for OAuth;
22  receivedRedirectUri: window.location.href,
23});
24
25handler.open();

Obtain an access token

When a user successfully links an Item via Link, the onSuccess callback will be called. The onSuccess callback returns a public token. On your application server, exchange the public token for an access token and an Item ID by calling /item/public_token/exchange/. The access token will allow you to make authenticated calls to the Plaid API.

Store the access token and Item ID in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. The access token will remain valid unless you actively expire it via rotation or remove it by calling /item/remove on the corresponding Item. For security purposes, never store the access token in client-side code. The public token is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

Exchange public token for an access token
Select group for content switcher
Select Language
1app.post('/api/exchange_public_token', async function (
2  request,
3  response,
4  next,
5) {
6  const publicToken = request.body.public_token;
7  try {
8    const response = await client.itemPublicTokenExchange({
9      public_token: publicToken,
10    });
11
12    // These values should be saved to a persistent database and
13    // associated with the currently signed-in user
14    const accessToken = response.data.access_token;
15    const itemID = response.data.item_id;
16
17    res.json({ public_token_exchange: 'complete' });
18  } catch (error) {
19    // handle error
20  }
21});

Getting Auth data

Now that you have an access token, you can begin making authenticated calls to the Plaid API. If you are processing payments yourself, the /auth/get endpoint to retrieve the bank account and bank identification numbers (such as routing numbers, for US accounts) associated with an Item's accounts. You can then supply these to your payment system. If you are using a Plaid partner to move funds, you will not need to call /auth/get. Instead, see Moving funds with a payment partner.

Select group for content switcher
Select Language
1const { AuthGetRequest } = require('plaid');
2
3// Call /auth/get and retrieve account numbers for an Item
4const request: AuthGetRequest = {
5  access_token: access_token,
6};
7try {
8  const response = await plaidClient.authGet(request);
9  const accountData = response.data.accounts;
10  if (response.data.numbers.ach.length > 0) {
11    // Handle ACH numbers (US accounts)
12    const achNumbers = response.data.numbers.ach;
13  }
14  if (response.data.numbers.eft.length > 0) {
15    // Handle EFT numbers (Canadian accounts)
16    const eftNumbers = response.data.numbers.eft;
17  }
18  if (response.data.numbers.international.length > 0) {
19    // Handle International numbers
20    const internationalNumbers = response.data.numbers.international;
21  }
22  if (response.data.numbers.bacs.length > 0) {
23    // Handle BACS numbers (British accounts)
24    const bacsNumbers = response.data.numbers.bacs;
25  }
26} catch (error) {
27  //handle error
28}

Example response data is below. Note that this is test account data; real accounts would not include all four sets of numbers.

1{
2  "accounts": [
3    {
4      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
5      "balances": {
6        "available": 100,
7        "current": 110,
8        "limit": null,
9        "iso_currency_code": "USD",
10        "unofficial_currency_code": null
11      },
12      "mask": "9606",
13      "name": "Plaid Checking",
14      "official_name": "Plaid Gold Checking",
15      "subtype": "checking",
16      "type": "depository"
17    }
18  ],
19  "numbers": {
20    "ach": [
21      {
22        "account": "9900009606",
23        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
24        "routing": "011401533",
25        "wire_routing": "021000021"
26      }
27    ],
28    "eft": [
29      {
30        "account": "111122223333",
31        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
32        "institution": "021",
33        "branch": "01140"
34      }
35    ],
36    "international": [
37      {
38        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
39        "bic": "NWBKGB21",
40        "iban": "GB29NWBK60161331926819"
41      }
42    ],
43    "bacs": [
44      {
45        "account": "31926819",
46        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
47        "sort_code": "601613"
48      }
49    ]
50  },
51  "item": {
52    "available_products": [
53      "balance",
54      "identity",
55      "payment_initiation",
56      "transactions"
57    ],
58    "billed_products": ["assets", "auth"],
59    "consent_expiration_time": null,
60    "error": null,
61    "institution_id": "ins_117650",
62    "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
63    "webhook": "https://www.genericwebhookurl.com/webhook"
64  },
65  "request_id": "m8MDnv9okwxFNBV"
66}

Moving funds with a payment partner

You can move money via ACH transfer by pairing Auth with one of Plaid's payment partners. When using a partner to move money, the partner's payments service will initiate the transfer; Plaid does not function as the payment processor. For the full list of payments platforms who have partnered with Plaid to provide ACH money movement, see Auth Partnerships.

To move money using a Plaid partner, first create an Item using Link and obtain an access token as described above. Then, instead of calling Plaid's Auth endpoints, call one of Plaid's processor token endpoints to create a processor token. You can then send this processor token to one of Plaid's partners by using endpoints that are specific to the payment platform. Refer to the partner's technical documentation for more information. Using a partner to transfer funds gives you access to payment functionality while freeing you from having to securely store sensitive bank account information.

The sample code below demonstrates a call to /processor/token/create using Dwolla as the payment processor.

Select group for content switcher
Select Language
1const { ProcessorTokenCreateRequest } = require('plaid');
2
3try {
4  // Create a processor token for a specific account id
5  const request: ProcessorTokenCreateRequest = {
6    access_token: accessToken,
7    account_id: accountID,
8    processor: 'dwolla',
9  };
10  const processorTokenResponse = await plaidClient.processorTokenCreate(
11    request,
12  );
13  const processorToken = processorTokenResponse.processor_token;
14} catch (error) {
15  // handle error
16}

Tutorial and example code in Plaid Pattern

For a real-life example of an app that incorporates Auth, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that fetches Auth data in order to set up funds transfers. The Auth code can be found in items.js.

For a step-by-step tutorial on how to implement account funding, Account funding tutorial.

Next steps

Once Auth is implemented in your app, see Full Auth coverage to make sure your app is supporting the maximum number of institutions (US only).

If your use case is an account funding use case, see the Account funding solutions guide for a set of recommendations on how to implement Auth.

If you're ready to launch to Production, see the Launch checklist.

balance add to app

Add Balance to your app

Use Balance to fetch real-time balance data

In this guide, we'll start from scratch and walk through how to use Balance to retrieve real-time balance information. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, make sure to note that you should not include balance in the /link/token/create products array; you can then skip ahead to Fetching balance data.

Get Plaid API keys and complete application and company profile

If you don't already have one, you'll need to create a Plaid developer account. After creating your account, you can find your API keys under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your application profile and company profile in the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the Plaid Portal. Your application profile and company profile must be completed before connecting to certain institutions in Production.

Install and initialize Plaid libraries

You can use our official server-side client libraries to connect to the Plaid API from your application:

Select group for content switcher
Select Language
1// Install via npm
2npm install --save plaid

After you've installed Plaid's client libraries, you can initialize them by passing in your client_id, secret, and the environment you wish to connect to (Sandbox, Development, or Production). This will make sure the client libraries pass along your client_id and secret with each request, and you won't need to explicitly include them in any other calls.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can obtain from the Dashboard. These code samples also demonstrate starting up a server commonly used in each framework (such as Express or Flask).

Select group for content switcher
Select Language
1// Using Express
2const express = require('express');
3const app = express();
4app.use(express.json());
5
6const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
7
8const configuration = new Configuration({
9  basePath: PlaidEnvironments.sandbox,
10  baseOptions: {
11    headers: {
12      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
13      'PLAID-SECRET': process.env.PLAID_SECRET,
14    },
15  },
16});
17
18const client = new PlaidApi(configuration);

Create an Item in Link

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the Link documentation.

Using Link, we will create a Plaid Item, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. If you want to customize Link's look and feel, you can do so from the Dashboard.

Before initializing Link, you will need to create a new link_token on the server side of your application. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the /link/token/create endpoint. Then, on the client side of your application, you'll need to initialize Link with the link_token that you just created.

balance cannot be used as a product when calling /link/token/create. You must create the link_token with the product or products you will be using with Balance, instead. You will then automatically get access to the Balance product.

Create a link_token
Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Install Link dependency
Select Language
1<head>
2  <title>Connect a bank</title>
3  <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
4</head>
Configure the client-side Link handler
1const linkHandler = Plaid.create({
2  token: (await $.post('/create_link_token')).link_token,
3  onSuccess: (public_token, metadata) => {
4    // Send the public_token to your app server.
5    $.post('/exchange_public_token', {
6      public_token: public_token,
7    });
8  },
9  onExit: (err, metadata) => {
10    // Optionally capture when your user exited the Link flow.
11    // Storing this information can be helpful for support.
12  },
13  onEvent: (eventName, metadata) => {
14    // Optionally capture Link flow events, streamed through
15    // this callback as your users connect an Item to Plaid.
16  },
17});
18
19linkHandler.open();

Get a persistent access_token

Next, on the server side, we need to exchange our public_token for an access_token and item_id. The access_token will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the /item/public_token/exchange endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the access_token and item_id in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. The access_token will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via /item/remove. The access_token should be stored securely, and never in client-side code. A public_token is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

Select group for content switcher
Select Language
1app.post('/api/exchange_public_token', async function (
2  request,
3  response,
4  next,
5) {
6  const publicToken = request.body.public_token;
7  try {
8    const response = await client.itemPublicTokenExchange({
9      public_token: publicToken,
10    });
11
12    // These values should be saved to a persistent database and
13    // associated with the currently signed-in user
14    const accessToken = response.data.access_token;
15    const itemID = response.data.item_id;
16
17    res.json({ public_token_exchange: 'complete' });
18  } catch (error) {
19    // handle error
20  }
21});

Fetching Balance data

Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API. Once you've retrieved balance data for an account, you can then use it to evaluate whether a potential transaction will go through. For more detailed information on the schema returned, see /accounts/balance/get.

Select group for content switcher
Select Language
1const { AccountsGetRequest } = require('plaid');
2
3// Pull real-time balance information for each account associated
4// with the Item
5const request: AccountsGetRequest = {
6  access_token: accessToken,
7};
8try {
9  const response = await plaidClient.accountsBalanceGet(request);
10  const accounts = response.data.accounts;
11} catch (error) {
12  // handle error
13}

Example response data is below.

1{
2  "accounts": [
3    {
4      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
5      "balances": {
6        "available": 100,
7        "current": 110,
8        "iso_currency_code": "USD",
9        "limit": null,
10        "unofficial_currency_code": null
11      },
12      "mask": "0000",
13      "name": "Plaid Checking",
14      "official_name": "Plaid Gold Standard 0% Interest Checking",
15      "subtype": "checking",
16      "type": "depository"
17    },
18    {
19      "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
20      "balances": {
21        "available": null,
22        "current": 410,
23        "iso_currency_code": "USD",
24        "limit": 2000,
25        "unofficial_currency_code": null
26      },
27      "mask": "3333",
28      "name": "Plaid Credit Card",
29      "official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
30      "subtype": "credit card",
31      "type": "credit"
32    },
33    {
34      "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
35      "balances": {
36        "available": null,
37        "current": 65262,
38        "iso_currency_code": "USD",
39        "limit": null,
40        "unofficial_currency_code": null
41      },
42      "mask": "7777",
43      "name": "Plaid Student Loan",
44      "official_name": null,
45      "subtype": "student",
46      "type": "loan"
47    }
48  ],
49  "item": {
50    "available_products": [
51      "balance",
52      "credit_details",
53      "identity",
54      "investments"
55    ],
56    "billed_products": ["assets", "auth", "liabilities", "transactions"],
57    "consent_expiration_time": null,
58    "error": null,
59    "institution_id": "ins_3",
60    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
61    "webhook": "https://www.genericwebhookurl.com/webhook"
62  },
63  "request_id": "qk5Bxes3gDfv4F2"
64}

Tutorial and example code in Plaid Pattern

For a real-life example of an app that incorporates Balance, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that fetches Balance data to check for sufficient funds before a funds transfer. The Balance code can be found in items.js.

For a tutorial walkthrough of creating a similar app, see Account funding tutorial.

Next steps

If you're ready to launch to Production, see the Launch checklist.

auth partnerships drivewealth

Add DriveWealth to your app

Use DriveWealth with Plaid Auth to send and receive payments!

Partnership DriveWealth logo

Overview

Plaid and DriveWealth have partnered to help customers seamlessly link bank accounts to their DriveWealth-supported investment products. DriveWealth offers the entire investor experience—everything from account creation through tax reporting—via a simple to use API. Using this integration, bank accounts connected via Plaid can be added to the DriveWealth platform for funding accounts or withdrawing money, without ever sharing sensitive account details.

To get started sign up for Plaid API keys.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified DriveWealth account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a DriveWealth processor_token, which allows you to quickly and securely verify a bank funding source via DriveWealth's API without having to store any sensitive banking information. Utilizing Plaid + DriveWealth enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and DriveWealth in order to use the Plaid + DriveWealth integration. You'll also need to enable your Plaid account for the DriveWealth integration.

First, you will need to work with the DriveWealth team to sign up for a DriveWealth account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for DriveWealth to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a DriveWealth processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with DriveWealth, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a DriveWealth processor_token. You'll send this token to DriveWealth and they will use it to securely retrieve account and routing numbers from Plaid.

You can create DriveWealth processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'drivewealth',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need DriveWealth Production credentials prior to initiating live payment transactions in the DriveWealth API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

account teams

Plaid teams

Learn about Plaid teams

Your Plaid dashboard account can create or join multiple teams to enable collaboration across different teams or companies.

You can be a member of multiple Plaid teams, each with their own API keys and billing information.

Creating a team

At the top-left of your Plaid Dashboard, click the team name drop-down and select Create new team.

Team menu

Once you have submitted your team name and purpose into the form, click Create team. Your new team will come with a fresh set of API keys which can be used to build a new Plaid integration.

Managing your team membership

You can create a new team, view your existing teams, and leave a team from the Personal menu, found at the bottom-left of your Plaid Dashboard:

Personal menu

Team-specific settings

Visit Settings > Team Settings in your Plaid Dashboard to view your company information, team members, billing settings, and invoices:

Managing team member permissions

From the Team Settings menu, you can also add and remove team members, as long as you have the Team management permission. You can assign specific permissions to each team member that you add to your Plaid team.

Members with the Support permission have view access to the Activity menus (Usage, Status, Logs and Payments), and the Support tab for filing support tickets.

Members with the Team management permission have access to the entire Developer Dashboard, including Plaid Link customization, API key management, and managing team membership.

You can also use this pane to control which development environments team members have access to. In order to view the team's public_key (if applicable) and client_id, team members must have access to at least one development environment.

Consolidating multiple accounts using teams

Teams prevent you from having to maintain multiple developer accounts. However, if you have already created multiple accounts, you can still consolidate them into a single account without having to create new keys or re-apply for access. To do so, follow these steps:

  1. Select an account to be the new primary account that will contain all the teams.

  2. From each account that you will be consolidating into the new primary account, invite the new primary account to the team.

  3. From each account that you will be consolidating into the new primary account, create a new empty team.

  4. From the new primary account, accept the invitations.

  5. From each account that you will be consolidating into the new primary account, leave the old team.

Your teams will now be consolidated under the new account.

Deleting a team

While you can leave teams, you cannot delete them, and you cannot leave a team if you are the last member in the team. In this case, please file a Deactivate my account support case if you wish to deactivate your team.

liabilities add to app

Add Liabilities to your app

Use Liabilities to fetch data for credit, student loan, and mortgage accounts

In this guide, we'll start from scratch and walk through how to use Liabilities to retrieve information about credit card, PayPal credit, student loan, and mortgage accounts. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, make sure to note that Liabilities supports the use of account subtype filtering; you can skip then ahead to Fetching Liabilities data.

Get Plaid API keys and complete application profile

If you don't already have one, you'll need to create a Plaid developer account. After creating your account, you can find your API keys under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your application profile on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the Plaid Portal. Your application profile must be completed before connecting to certain institutions in Production.

Install and initialize Plaid libraries

You can use our official server-side client libraries to connect to the Plaid API from your application:

Select group for content switcher
Select Language
1// Install via npm
2npm install --save plaid

After you've installed Plaid's client libraries, you can initialize them by passing in your client_id, secret, and the environment you wish to connect to (Sandbox, Development, or Production). This will make sure the client libraries pass along your client_id and secret with each request, and you won't need to explicitly include them in any other calls.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can obtain from the Dashboard. These code samples also demonstrate starting up a server commonly used in each framework (such as Express or Flask).

Select group for content switcher
Select Language
1// Using Express
2const express = require('express');
3const app = express();
4app.use(express.json());
5
6const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
7
8const configuration = new Configuration({
9  basePath: PlaidEnvironments.sandbox,
10  baseOptions: {
11    headers: {
12      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
13      'PLAID-SECRET': process.env.PLAID_SECRET,
14    },
15  },
16});
17
18const client = new PlaidApi(configuration);

Create an Item in Link

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the Link documentation.

Using Link, we will create a Plaid Item, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts.

First, on the client side of your application, you'll need to set up and configure Link. If you want to customize Link's look and feel, you can do so from the Dashboard.

When initializing Link, you will need to specify the products you will be using in the product array.

Liabilities supports the use of the account_filters parameter to /link/token/create, which you can use to limit the account types that will be shown in Link to either only credit card accounts, only student loan accounts, or only mortgage accounts. For student loans, use the type loan and subtype student. For credit cards, use the type credit and subtype credit card. For mortgages, use the type loan and subtype mortgage.

Create a link_token
Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['liabilities'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Install Link dependency
Select Language
1<head>
2  <title>Connect a bank</title>
3  <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
4</head>
Configure the client-side Link handler
1const linkHandler = Plaid.create({
2  token: (await $.post('/create_link_token')).link_token,
3  onSuccess: (public_token, metadata) => {
4    // Send the public_token to your app server.
5    $.post('/exchange_public_token', {
6      public_token: public_token,
7    });
8  },
9  onExit: (err, metadata) => {
10    // Optionally capture when your user exited the Link flow.
11    // Storing this information can be helpful for support.
12  },
13  onEvent: (eventName, metadata) => {
14    // Optionally capture Link flow events, streamed through
15    // this callback as your users connect an Item to Plaid.
16  },
17});
18
19linkHandler.open();

Get a persistent access_token

Next, on the server side, we need to exchange our public_token for an access_token and item_id. The access_token will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the /item/public_token/exchange endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the access_token and item_id in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. The access_token will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via /item/remove. The access_token should be stored securely, and never in client-side code. A public_token is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

Select group for content switcher
Select Language
1app.post('/api/exchange_public_token', async function (
2  request,
3  response,
4  next,
5) {
6  const publicToken = request.body.public_token;
7  try {
8    const response = await client.itemPublicTokenExchange({
9      public_token: publicToken,
10    });
11
12    // These values should be saved to a persistent database and
13    // associated with the currently signed-in user
14    const accessToken = response.data.access_token;
15    const itemID = response.data.item_id;
16
17    res.json({ public_token_exchange: 'complete' });
18  } catch (error) {
19    // handle error
20  }
21});

Fetching Liabilities data

Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API. For more detailed information on the schema for account information returned, see /liabilities/get.

Select group for content switcher
Select Language
1const { LiabilitiesGetRequest } = require('plaid');
2
3// Retrieve Liabilities data for an Item
4const request: LiabilitiesGetRequest = {
5  access_token: accessToken,
6};
7try {
8  const response = await plaidClient.liabilitiesGet(request);
9  const liabilities = response.data.liabilities;
10} catch (error) {
11  // handle error
12}

Example response data is below. The data provided is for illustrative purposes; in a Production environment, it would be very unusual for a single institution to provide both credit card and student loan data.

1{
2  "accounts": [
3    {
4      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
5      "balances": {
6        "available": 100,
7        "current": 110,
8        "iso_currency_code": "USD",
9        "limit": null,
10        "unofficial_currency_code": null
11      },
12      "mask": "0000",
13      "name": "Plaid Checking",
14      "official_name": "Plaid Gold Standard 0% Interest Checking",
15      "subtype": "checking",
16      "type": "depository"
17    },
18    {
19      "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
20      "balances": {
21        "available": null,
22        "current": 410,
23        "iso_currency_code": "USD",
24        "limit": 2000,
25        "unofficial_currency_code": null
26      },
27      "mask": "3333",
28      "name": "Plaid Credit Card",
29      "official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
30      "subtype": "credit card",
31      "type": "credit"
32    },
33    {
34      "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
35      "balances": {
36        "available": null,
37        "current": 65262,
38        "iso_currency_code": "USD",
39        "limit": null,
40        "unofficial_currency_code": null
41      },
42      "mask": "7777",
43      "name": "Plaid Student Loan",
44      "official_name": null,
45      "subtype": "student",
46      "type": "loan"
47    },
48    {
49      "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
50      "balances": {
51        "available": null,
52        "current": 56302.06,
53        "iso_currency_code": "USD",
54        "limit": null,
55        "unofficial_currency_code": null
56      },
57      "mask": "8888",
58      "name": "Plaid Mortgage",
59      "official_name": null,
60      "subtype": "mortgage",
61      "type": "loan"
62    }
63  ],
64  "item": {
65    "available_products": ["balance", "credit_details", "investments"],
66    "billed_products": [
67      "assets",
68      "auth",
69      "identity",
70      "liabilities",
71      "transactions"
72    ],
73    "consent_expiration_time": null,
74    "error": null,
75    "institution_id": "ins_3",
76    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
77    "webhook": "https://www.genericwebhookurl.com/webhook"
78  },
79  "liabilities": {
80    "credit": [
81      {
82        "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
83        "aprs": [
84          {
85            "apr_percentage": 15.24,
86            "apr_type": "balance_transfer_apr",
87            "balance_subject_to_apr": 1562.32,
88            "interest_charge_amount": 130.22
89          },
90          {
91            "apr_percentage": 27.95,
92            "apr_type": "cash_apr",
93            "balance_subject_to_apr": 56.22,
94            "interest_charge_amount": 14.81
95          },
96          {
97            "apr_percentage": 12.5,
98            "apr_type": "purchase_apr",
99            "balance_subject_to_apr": 157.01,
100            "interest_charge_amount": 25.66
101          },
102          {
103            "apr_percentage": 0,
104            "apr_type": "special",
105            "balance_subject_to_apr": 1000,
106            "interest_charge_amount": 0
107          }
108        ],
109        "is_overdue": false,
110        "last_payment_amount": 168.25,
111        "last_payment_date": "2019-05-22",
112        "last_statement_issue_date": "2019-05-28",
113        "last_statement_balance": 1708.77,
114        "minimum_payment_amount": 20,
115        "next_payment_due_date": "2020-05-28"
116      }
117    ],
118    "mortgage": [
119      {
120        "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
121        "account_number": "3120194154",
122        "current_late_fee": 25.0,
123        "escrow_balance": 3141.54,
124        "has_pmi": true,
125        "has_prepayment_penalty": true,
126        "interest_rate": {
127          "percentage": 3.99,
128          "type": "fixed",
129        },
130        "last_payment_amount": 3141.54,
131        "last_payment_date": "2019-08-01",
132        "loan_term": "30 year",
133        "loan_type_description": "conventional",
134        "maturity_date": "2045-07-31",
135        "next_monthly_payment": 3141.54,
136        "next_payment_due_date": "2019-11-15",
137        "origination_date": "2015-08-01",
138        "origination_principal_amount": 425000,
139        "past_due_amount": 2304,
140        "property_address": {
141          "city": "Malakoff",
142          "country": "US",
143          "postal_code": "14236",
144          "region": "NY",
145          "street": "2992 Cameron Road",
146        }
147        "ytd_interest_paid": 12300.4,
148        "ytd_principal_paid": 12340.5
149      }
150    ],
151    "student": [
152      {
153        "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
154        "account_number": "4277075694",
155        "disbursement_dates": ["2002-08-28"],
156        "expected_payoff_date": "2032-07-28",
157        "guarantor": "DEPT OF ED",
158        "interest_rate_percentage": 5.25,
159        "is_overdue": false,
160        "last_payment_amount": 138.05,
161        "last_payment_date": "2019-04-22",
162        "last_statement_issue_date": "2019-04-28",
163        "loan_name": "Consolidation",
164        "loan_status": {
165          "end_date": "2032-07-28",
166          "type": "repayment"
167        },
168        "minimum_payment_amount": 25,
169        "next_payment_due_date": "2019-05-28",
170        "origination_date": "2002-08-28",
171        "origination_principal_amount": 25000,
172        "outstanding_interest_amount": 6227.36,
173        "payment_reference_number": "4277075694",
174        "pslf_status": {
175          "estimated_eligibility_date": "2021-01-01",
176          "payments_made": 200,
177          "payments_remaining": 160
178        },
179        "repayment_plan": {
180          "description": "Standard Repayment",
181          "type": "standard"
182        },
183        "sequence_number": "1",
184        "servicer_address": {
185          "city": "San Matias",
186          "country": "US",
187          "postal_code": "99415",
188          "region": "CA",
189          "street": "123 Relaxation Road"
190        },
191        "ytd_interest_paid": 280.55,
192        "ytd_principal_paid": 271.65
193      }
194    ]
195  },
196  "request_id": "dTnnm60WgKGLnKL"
197}

Next steps

If you're ready to launch to Production, see the Launch checklist.

sandbox test credentials

Sandbox test credentials

Simulate different flows using Sandbox credentials

Sandbox simple test credentials

The easiest approach to create Items in the Sandbox is by using the username user_good. This gives you some limited control over Sandbox Item creation flow. It is not as flexible as the custom Sandbox, as Item details such as accounts and transactions are hardcoded.

1username: user_good
2password: pass_good
3pin: credential_good (when required)

Sandbox multi-factor credentials

You can trigger any multi-factor authentication (MFA) flow that Plaid supports when creating an Item by using username user_good and modifying the password.

Bank of America and U.S. Bank cannot be used as test institutions when triggering MFA flows with modified passwords. Instead, these banks will always launch on Sandbox with an MFA flow.

Multi-factor device OTP
1username: 'user_good'
2password: 'mfa_device'
3
4# Code for all devices: 1234
5code: 1234
Multi-factor questions
1# n-rounds of m-questions per round, where 0 <= i, j < 9
2username: 'user_good'
3password: 'mfa_questions_<n>_<m>'
4
5# answer_<i>_<j>, for j-th question in i-th round.
6answer: 'answer_<i>_<j>'
Multi-factor selections
1username: 'user_good'
2password: 'mfa_selections'
3
4answer: 'Yes'
1# n-rounds of m-questions with o-answers per question
2# 0 < n, m < 10 and 2 <= o < 10
3username: 'user_good'
4password: 'mfa_selections_<n>_<m>_<o>'
5
6# answer_<n>_<m>_0, for m-th question in n-th round.
7answer: 'answer_1_1_0'

ReCAPTCHA testing credentials

You may trigger a reCAPTCHA in Plaid Link in the Sandbox environment by customizing the test account password. Possible values are good or bad. A value of good will result in successful Item creation and bad will result in a RECAPTCHA_BAD error to simulate a failed reCAPTCHA. Both values require the reCAPTCHA to be manually solved within Plaid Link.

1username: user_good
2password: {"recaptcha":"bad"}

Error testing credentials

You can trigger several ITEM_ERROR or INSTITUTION_ERROR errors that you may encounter when creating an Item by using username user_good and modifying the password.

1error_[ERROR_CODE]

For example, the password error_ITEM_LOCKED allows you to simulate an ITEM_LOCKED error.

Note that error testing credentials are not compatible with institutions that use OAuth. If you are not sure whether an institution uses OAuth flows, see the list of Sandbox institutions to find an institution that is guaranteed not to use OAuth.

The list of errors that can be simulated in this way is below:

1"COUNTRY_NOT_SUPPORTED"
2"INSTITUTION_DOWN"
3"INSTITUTION_NOT_RESPONDING"
4"INSTITUTION_NO_LONGER_SUPPORTED"
5"INSUFFICIENT_CREDENTIALS"
6"INTERNAL_SERVER_ERROR"
7"INVALID_CREDENTIALS"
8"INVALID_MFA"
9"INVALID_SEND_METHOD"
10"ITEM_LOCKED"
11"ITEM_NOT_SUPPORTED"
12"MFA_NOT_SUPPORTED"
13"NO_ACCOUNTS"
14"PAYMENT_INVALID_RECIPIENT"
15"PRODUCTS_NOT_SUPPORTED"
16"USER_INPUT_TIMEOUT"
17"USER_SETUP_REQUIRED"

Auth micro-deposit testing credentials

For automated micro-deposit testing, use the username user_good with the password microdeposits_good. For more details, see Institution details for Auth testing.

Monitor and Identity Verification testing users

Monitor and Identity Verification have product-specific Sandbox users that can be used for testing. For more details, see Testing Monitor and Testing Identity Verification.

Bank Income testing credentials

For Bank Income testing, use the username user_bank_income with the password {}. For more details, see Testing Bank Income.

errors transfer

Transfer errors

Errors specific to the Transfer product

PAYMENT_PROFILE_NOT_READY

This Payment Profile has not been associated with a user via a Link session.
Common causes
  • You are attempting to use a Payment Profile that has not been associated with a user via a Link session.
  • You are using Payment Profiles in Sandbox with an Item created via /sandbox/public_token/create.
Troubleshooting steps
1http code 400
2{
3 "error_type": "TRANSFER_ERROR",
4 "error_code": "PAYMENT_PROFILE_NOT_READY",
5 "error_message": "this payment profile is not ready to be used",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

TRANSFER_LIMIT_EXCEEDED

The attempted transfer exceeded the account's daily transfer or single transfer limits.
Common causes
  • The attempted transfer exceeded the account's daily transfer or single transfer limits. The error message will indicate which transfer limit was exceeded.
Troubleshooting steps
1http code 400
2{
3 "error_type": "TRANSFER_ERROR",
4 "error_code": "TRANSFER_LIMIT_EXCEEDED",
5 "error_message": "transfer limit exceeded",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

TRANSFER_MISSING_ORIGINATION_ACCOUNT

There are multiple origination accounts available for the transfer, but which account to use was not specified.
Common causes
  • There is more than one origination account associated with the client id, but no account was specified in the request.
Troubleshooting steps
1http code 400
2{
3 "error_type": "TRANSFER_ERROR",
4 "error_code": "TRANSFER_MISSING_ORIGINATION_ACCOUNT",
5 "error_message": "origination_account_id is required",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

TRANSFER_INVALID_ORIGINATION_ACCOUNT

The origination account specified for the transfer was invalid.
Common causes
Troubleshooting steps
1http code 400
2{
3 "error_type": "TRANSFER_ERROR",
4 "error_code": "TRANSFER_INVALID_ORIGINATION_ACCOUNT",
5 "error_message": "origination_account_id is invalid",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

TRANSFER_ACCOUNT_BLOCKED

The transfer could not be completed because a previous transfer involving the same end-user account resulted in an error.
Common causes
  • Plaid has flagged the end-user's account as not valid for use with Transfer.
Troubleshooting steps
1http code 400
2{
3 "error_type": "TRANSFER_ERROR",
4 "error_code": "TRANSFER_ACCOUNT_BLOCKED",
5 "error_message": "transfer was blocked due to a previous ACH return on this account",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

TRANSFER_NOT_CANCELLABLE

The transfer could not be canceled.
Common causes
  • An attempt was made to cancel a transfer that has already been sent to the network for execution and cannot be cancelled at this stage.
Troubleshooting steps
1http code 400
2{
3 "error_type": "TRANSFER_ERROR",
4 "error_code": "TRANSFER_NOT_CANCELLABLE",
5 "error_message": "transfer is not cancellable",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

TRANSFER_UNSUPPORTED_ACCOUNT_TYPE

An attempt was made to transfer funds to or from an unsupported account type.
Common causes
  • An attempt was made to transfer funds to or from an unsupported account type. Only checking and savings accounts can be used with Transfer. In addition, if the transfer is a debit transfer, the account must be a debitable account.
Troubleshooting steps
1http code 400
2{
3 "error_type": "TRANSFER_ERROR",
4 "error_code": "TRANSFER_UNSUPPORTED_ACCOUNT_TYPE",
5 "error_message": "transfer account type not supported",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

TRANSFER_FORBIDDEN_ACH_CLASS

An attempt was made create a transfer with a forbidden ACH class (SEC code).
Common causes

  • Your Plaid account has not been enabled for the ACH class specified in the request.

  • The ACH class specified in the transfer request was incorrect.

Troubleshooting steps
1http code 400
2{
3 "error_type": "TRANSFER_ERROR",
4 "error_code": "TRANSFER_FORBIDDEN_ACH_CLASS",
5 "error_message": "specified ach_class is forbidden",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

TRANSFER_UI_UNAUTHORIZED

The client is not enabled for the Transfer UI product.
Common causes
  • Your account is not enabled for use with Transfer UI.
Troubleshooting steps
1http code 400
2{
3 "error_type": "TRANSFER_ERROR",
4 "error_code": "TRANSFER_UI_UNAUTHORIZED",
5 "error_message": "client is not authorized for transfer UI",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

ACH return codes

Prefer to learn by watching? A video guide is available for this topic.

All returned ACH transactions will have an ACH return code. By reading the code, you can troubleshoot and debug returned transactions.

Return CodeDescriptionNotes
R01Insufficient fundsAvailable balance is not sufficient to cover the dollar amount of the debit entry
R02Account closedA previously open account is now closed
R03No account or unable to locate accountThe account number does not correspond to the individual identified in the entry or a valid account
R04Invalid account numberThe account number fails the check digit validation or may contain an incorrect number of digits
R05Unauthorized debit to consumer accountA business debit entry was transmitted to a member’s consumer account, and the member had not authorized the entry
R06Returned per ODFI's requestThe ODFI has requested that the RDFI return the entry
R07Authorization revoked by customerMember who previously authorized an entry has revoked authorization with the originator
R08Payment stopped or stop payment on itemMember had previously requested a stop payment of a single or recurring entry
R09Uncollected fundsAvailable balance is sufficient, but the collected balance is not sufficient to cover the entry
R10Customer advises not authorizedMember advises not authorized, notice not provided, improper source document, or amount of entry not accurately obtained from source document
R11Check truncation entry returnTo be used when returning a check truncation entry
R12Branch sold to another DFIRDFI unable to post entry destined for a bank account maintained at a branch sold to another financial institution
R13Invalid ACH routing numberFinancial institution does not receive commercial ACH entries
R14Representative payee deceased or unable to continue in that capacityRepresentative payee is deceased or unable to continue in that capacity, beneficiary is not deceased
R15Beneficiary of account holder deceasedBeneficiary or Account Holder Deceased
R16Account frozenAccess to account is restricted due to a specific action taken by the RDFI or by legal action
R17File record edit criteriaFields rejected by RDFI processing (identified in return addenda)
R18Improper effective entryEntries have been presented prior to the first available processing window for the effective date
R19Amount field errorImproper formatting of the amount field
R20Non-transaction accountPolicies or regulations (such as Regulation D) prohibit or limit activity to the account indicated
R21Invalid company identificationThe company ID information not valid (normally CIE entries)
R22Invalid individual ID numberIndividual id used by receiver is incorrect (CIE entries)
R23Credit entry refused by receiverReceiver returned entry because minimum or exact amount not remitted, bank account is subject to litigation, or payment represents an overpayment, originator is not known to receiver or receiver has not authorized this credit entry to this bank account
R24Duplicate entryRDFI has received a duplicate entry
R25Addenda errorImproper formatting of the addenda record information
R26Mandatory field errorImproper information in one of the mandatory fields
R27Trace number errorOriginal entry trace number is not valid for return entry; or addenda trace numbers do not correspond with entry detail record
R28Routing number or check digitCheck digit for transit routing number is incorrect
R29Corporate customer advises not authorizedRDFI has been notified by business account holder that a specific transaction is unauthorized
R30RDFI not participant in check truncation programFinancial institution not participating in automated check safekeeping application
R31Permissible return entryRDFI has been notified by business account holder that a specific transaction is unauthorized
R32RDFI non settlementRDFI is not able to settle the entry
R33Return of XCK entryRDFI determines at its sole discretion to return an XCK entry; an XCK return entry may be initiated by midnight of the sixtieth day following the settlement date if the XCK entry
R34Limited participation DFIRDFI participation has been limited by a federal or state supervisor
R35Return of improper debit entryACH debit not permitted for use with the CIE standard entry class code (except for reversals)
R36Return of improper credit entry
R37Source Document Presented for PaymentCheck used for an ARC, BOC or POP entry has also been presented for payment
R38Stop payment on source documentStop payment has been placed on a check used for an ARC entry
R40Return of ENR entry by federal government agency (ENR only)
R41Invalid transaction code (ENR only)
R42Routing number or check digit error (ENR only)
R43Invalid DFI account number (ENR only)
R44Invalid individual ID number (ENR only)
R45Invalid individual name/company name (ENR only)
R46Invalid representative payee indicator (ENR only)
R47Duplicate enrollment
R50State law affecting RCK acceptance
R51Item is ineligible, notice not provided, signature not genuine
R52Stop payment on item
R61Misrouted returnReturn entry was sent by RDFI to an incorrect ODFI routing/transit number
R62Incorrect trace number
R63Incorrect dollar amount
R64Incorrect individual identification
R65Incorrect transaction code
R66Incorrect company identification
R67Duplicate returnODFI has received more than one return entry for the same original entry
R68Untimely returnReturn entry did not meet the return deadline
R69Multiple errors
R70Permissible return entry not accepted
R71Misrouted dishonored return
R72Untimely dishonored return
R73Timely original return
R74Corrected return
R80Cross-border payment coding error
R81Nonparticipant in cross-border program
R82Invalid foreign receiving DFI identification

RTP error codes

failed RTP transactions will have a failure description. By reading the description, you can troubleshoot and debug failed transactions.

DescriptionNotes
Cannot parse the message
Signature mismatch or verification error
Debtor account is invalid
Creditor account is invalid
Account closed
Account is blocked
Creditor account closed
Debtor account currency is invalid or missing
Creditor account currency is invalid or missing
Debtor account type missing or invalid
Creditor account type missing or invalid
Transaction is forbidden on this type of account
Transaction type is not supported/authorized on this account
Incorrect Agent
Specific transaction/message amount is greater than allowed maximum
Amount of funds available to cover specified message amount is insufficientInsufficient Funds
Amount received is not the amount agreed or expected
Transaction currency is invalid or missing
Amount is invalid or missing
Transaction amount exceeds limits set by clearing system
Transaction Amount exceeds limits agreed between bank and client
Specification of creditor's address, which is required for payment, is missing / not correct
End customer specified is not known at associated Sort/National Bank Code or no longer exist
Specification of debtor's address, which is required for payment, is missing / not correct
Debtor country code is missing or invalid
Creditor country code is missing or invalid
Country code of debtor’s residence is missing or Invalid
Country code of creditor's residence is missing or Invalid
Debtor identification code missing or invalid
Creditor identification code missing or invalid
Waiting time expired due to incomplete orderReceiving bank timed out
Future date is not supported
Payment is a duplicate of another payment
Signer is not allowed to sign for this account
Syntax error reason is provided as narrative information in the additional reason information
Invalid Payment Type Information
End to End Id is missing or invalid
End customer is deceased
Reason is provided as narrative information in the additional reason information
Bank identifier code specified in the message has an incorrect format
Bank Identified is invalid or missing
Debtor FI identifier is invalid or missing
Creditor FI identifier is invalid or missing
Invalid Cut Off Time
Invalid Token
Sender Token Not Found
Receiver Token Not Found
Token Expired
Token Found with Counterparty Mismatch
Token Found with Value Limit Rule Violation
Single Use Token Already Used
Token Suspended
Receiving Customer Account does not support/accept this message type
Completed
Any Other Reasons Reason is provided as narrative in the additional information
Central Switch (RTP) system malfunction
Instructed Agent signed-off
Recipient connection is not available
Instructing Agent signed-off
Instructing Agent suspended
Instructed Agent suspended
Central Switch (RTP) service is suspended

auth partnerships vopay

Add VoPay to your app

Use VoPay with Plaid Auth to send and receive payments!

Partnership VoPay logo

Overview

VoPay is a leader in payment innovation, digitizing direct bank payments with speed and transparency. The VoPay Platform enhances how digital platforms initiate and accept financial transactions using a single, open API. The company has one goal: to eliminate all payment inefficiencies, so businesses can focus on what they do best in today’s fast-paced digital economy. VoPay’s EFT / ACH payment service adds a layer of data intelligence to EFT / ACH transactions to make them instant. With the Plaid integration, VoPay will validate and authenticate bank account information at the time of the transaction

To get started sign up for Plaid API keys.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified VoPay account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a VoPay processor_token, which allows you to quickly and securely verify a bank funding source via VoPay's API without having to store any sensitive banking information. Utilizing Plaid + VoPay enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and VoPay in order to use the Plaid + VoPay integration. You'll also need to enable your Plaid account for the VoPay integration.

First, you will need to work with the VoPay team to sign up for a VoPay account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for VoPay to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a VoPay processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with VoPay, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a VoPay processor_token. You'll send this token to VoPay and they will use it to securely retrieve account and routing numbers from Plaid.

You can create VoPay processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'vopay',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need VoPay Production credentials prior to initiating live payment transactions in the VoPay API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

transfer using transfer ui

Sending or Receiving Funds Using Transfer UI

Facilitate transfers with an intuitive user interface

Overview

Transfer UI requires that both the sender and recipient reside within the United States. It is only supported in Plaid's Sandbox and Production environments.

Transfer UI is not compatible with Platform Payments.

Plaid Transfer UI is a user interface that makes it easy for end users to authorize transfers. With Transfer UI, users are able to authorize two types of transfers: payments or disbursements. Before authorizing a transfer, users are able to review transfer details, such as amount, fund origination account, fund target account, and more.

Prefer to learn by watching? Get an overview of how Transfer UI works in just 3 minutes!

Transfer UI also provides the same series of return risk checks that are provided by a direct API integration with the Transfer API. These checks analyze proposed transfers and inform users of any potential problems with a transfer. When a potential return is detected, users can remediate the problem within the UI.

Transfer UI process overview

  1. Call /transfer/intent/create to obtain a transfer_intent.id.

  2. Call /link/token/create, specifying transfer in the products parameter, the transfer_intent.id in the transfer.intent_id parameter, and the name of your Link customization in the link_customization_name parameter. If you already have an access_token for this user, you can provide it to /link/token/create to streamline the Link flow.

  3. Initialize a Link instance using the link_token created in the previous step. For more details for your specific platform, see the Link documentation.

  4. The user will now go through the Link flow to perform their transfer. The onSuccess callback will indicate they have completed the Link flow.

  5. (Optional) You will receive a public_token from the onSuccess callback. If you do not already have an access token for this user's account, call /item/public_token/exchange to exchange this public token for an access_token in order to streamline future transfers for this user.

Prerequisites for using Transfer UI

The following prerequisites are enabled by default for all new Plaid customers; however, some developers on legacy accounts may be using older configurations.

Creating a Link customization

In the Plaid Dashboard, create a customization for Transfer UI with the Account Select behavior set to "Enabled for one account". This is the only Account Select behavior supported by Transfer UI. Note that you must also have Account Select v2 enabled.

Generating a transfer intent object

To use Transfer UI, call the /transfer/intent/create endpoint. This endpoint invokes the Transfer UI and generates a transfer intent object. Take special note of the id field returned in the transfer intent object. The value of this field is Plaid's unique identifier for the transfer intent object and can be used later to track the status of a transfer intent.

Select Language
1const request: TransferIntentCreateRequest = {
2  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
3  mode: 'PAYMENT'
4  amount: '12.34',
5  description: 'Foobar',
6  ach_class: 'ppd',
7  user: {
8    legal_name: 'Leslie Knope',
9  }
10};
11
12try {
13  const response = await client.transferIntentCreate(request);
14} catch (error) {
15  // handle error
16}
1{
2  "transfer_intent": {
3    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
4    "ach_class": "ppd",
5    "amount": "12.34",
6    "iso_currency_code": "USD",
7    "created": "2020-08-06T17:27:15Z",
8    "description": "Foobar",
9    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
10    "metadata": {
11      "key1": "value1",
12      "key2": "value2"
13    },
14    "mode": "PAYMENT",
15    "origination_account_id": "9853defc-e703-463d-86b1-dc0607a45359",
16    "status": "PENDING",
17    "user": {
18      "address": {
19        "street": "100 Market Street",
20        "city": "San Francisco",
21        "region": "CA",
22        "postal_code": "94103",
23        "country": "US"
24      },
25      "email_address": "lknope@email.com",
26      "legal_name": "Leslie Knope",
27      "phone_number": "123-456-7890"
28    }
29  },
30  "request_id": "saKrIBuEB9qJZno"
31}

Generating a Link token with the transfer intent ID

Generate a Link token by calling /link/token/create and specify the following:

  • "transfer", in the products array. Ensure that "transfer" is the only product being initialized.

  • A transfer object in the body of the create request. Within the transfer object, specify the transfer intent ID using the value of id returned by /transfer/intent/create.

  • The name of your Link customization for Transfer UI. For more details on creating this Link customization, see Creating a Link customization.

  • If you already have an access token, provide it in the access_token parameter to streamline the user's Link flow. If you do not have an access token, you will have the opportunity to create one after the Transfer is complete.

Select Language
1const request: LinkTokenCreateRequest = {
2  user: {
3    client_user_id: 'user-id',
4  },
5  client_name: 'Plaid App',
6  products: ['transfer'],
7  country_codes: ['US'],
8  language: 'en',
9  webhook: 'https://sample-web-hook.com',
10  redirect_uri: 'https://domainname.com/oauth-page.html',
11  transfer: {
12    intent_id: 'TRANSFER_INTENT_ID',
13  },
14  account_filters: {
15    depository: {
16      account_subtypes: [
17        'DepositoryAccountSubtype.Checking, DepositoryAccountSubtype.Savings',
18      ],
19    },
20  },
21  link_customization_name: 'single-account-select-transfer-ui',
22};
23try {
24  const response = await plaidClient.linkTokenCreate(request);
25  const linkToken = response.data.link_token;
26} catch (error) {
27  // handle error
28}

Once you have a link token, you can provide it to Link in order to initialize a Link session. The user can then transfer funds within the Link flow. For more details, see Link.

Select Language
1const handler = Plaid.create({
2  token: 'GENERATED_LINK_TOKEN',
3  onSuccess: (public_token, metadata) => {},
4  onLoad: () => {},
5  onExit: (err, metadata) => {},
6  onEvent: (eventName, metadata) => {},
7  //required for OAuth; if not using OAuth, set to null or omit:
8  receivedRedirectUri: window.location.href,
9});

If the user successfully completes their transfer, Link will emit an onSuccess callback containing a public_token. If you would like to save the user's payment information to make subsequent transfers faster, retrieve this public_token and call /item/public_token/exchange to exchange it for an access_token. If this access token is provided to /link/token/create when initializing Link for subsequent transfers, the user will be able to skip entering their login credentials.

Initializing Link with the generated token

Next, initialize Link using the Link token you generated, and then open Link. If a new Item is being created, end users will first be prompted to link their bank account via Link before they can authorize and review the transfer. For existing Items (where an access token has been stored for the associated Item), end users will bypass the account linking flow in Link and immediately be able to authorize and review the proposed transfer.

When integrating Transfer UI, it's best to store access tokens associated with Items so that you can use them when invoking subsequent transfer requests. This will provide end users with an expedited Transfer UI experience by allowing them to bypass the account linking flow in Link so that they can quickly authorize and review transfers.

For more information on initializing Link, see Plaid Link: Web.

1const handler = Plaid.create({
2  token: 'GENERATED_LINK_TOKEN',
3  onSuccess: (public_token, metadata) => {},
4  onLoad: () => {},
5  onExit: (err, metadata) => {},
6  onEvent: (eventName, metadata) => {},
7  receivedRedirectUri: null,
8});
9
10// Open Link
11handler.open();

Tracking transfer creation

The instructions in this section correspond to the Web and Webview libraries for Link. If you're using a mobile SDK, information about the transfer intent status can be found in the metadataJson field in the SDK's onSuccess callback. As an example, see Android: metadataJson.

You can determine whether a transfer was successfully created by referring to the transfer_status field in the metadata object returned by onSuccess. A value of complete indicates that the transfer was successfully originated. A value of incomplete indicates that the transfer was not originated. Note that this field only indicates the status of a transfer creation. It does not indicate the status of a transfer (i.e., funds movement). For more information on transfer intents, see Retrieving additional information about transfer intents. For help troubleshooting incomplete transfers, see Troubleshooting transfers.

In addition, when using Transfer UI, the onSuccess callback is called at a different point in time in the Link flow. Typically, the onSuccess callback is called after an account is successfully linked using Link. When using Transfer UI, however, the onSuccess callback is called only after both of the following conditions are met: an account is successfully linked using Link and a transfer is confirmed via the UI. Note that the onSuccess callback only indicates that an account was successfully linked. It does not indicate a successful transfer (i.e., funds movement).

1{
2  institution: {
3    name: 'Wells Fargo',
4    institution_id: 'ins_4'
5  },
6  accounts: [
7    {
8      id: 'ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy',
9      name: 'Plaid Checking',
10      mask: '0000',
11      type: 'depository',
12      subtype: 'checking',
13      verification_status: ''
14    },
15    {
16      id: '9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4',
17      name: 'Plaid Saving',
18      mask: '1111',
19      type: 'depository',
20      subtype: 'savings'
21    }
22    ...
23  ],
24  transfer_status: 'incomplete',
25  link_session_id: '79e772be-547d-4c9c-8b76-4ac4ed4c441a'
26}

Retrieving additional information about transfer intents

To retrieve more information about a transfer intent, call the /transfer/intent/get endpoint and pass in a transfer intent id (returned by the /transfer/intent/create endpoint).

Select Language
1const request: TransferIntentGetRequest = {
2  transfer_intent_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
3};
4
5try {
6  const response = await client.transferIntentGet(request);
7} catch (error) {
8  // handle error
9}
1{
2  "transfer_intent": {
3    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
4    "ach_class": "ppd",
5    "amount": "15.75",
6    "authorization_decision": "APPROVED",
7    "authorization_decision_rationale": null,
8    "created": "2020-08-06T17:27:15Z",
9    "description": "Desc",
10    "failure_reason": null,
11    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
12    "metadata": {
13      "key1": "value1",
14      "key2": "value2"
15    },
16    "mode": "DISBURSEMENT",
17    "origination_account_id": "9853defc-e703-463d-86b1-dc0607a45359",
18    "status": "SUCCEEDED",
19    "transfer_id": "8945fedc-e703-463d-86b1-dc0607b55460",
20    "user": {
21      "address": {
22        "street": "100 Market Street",
23        "city": "San Francisco",
24        "region": "California",
25        "postal_code": "94103",
26        "country": "US"
27      },
28      "email_address": "lknope@email.com",
29      "legal_name": "Leslie Knope",
30      "phone_number": "123-456-7890"
31    }
32  },
33  "request_id": "saKrIBuEB9qJZno"
34}

The response is a transfer_intent object with more information about the transfer intent.

The status field in the response indicates whether the transfer intent was successfully captured. It can have one of the following values: FAILED, SUCCEEDED, or PENDING.

If the value of status is FAILED, the transfer intent was not captured. The transfer_id field will be "null" and the failure_reason object will contain information about why the transfer intent failed. Some possible reasons may include: the authorization was declined, the account is blocked, or the origination account was invalid.

If the value of status is SUCCEEDED, the transfer intent was successfully captured. The accompanying transfer_id field in the response will be set to the ID of the originated transfer. This ID can be used with other Transfer API endpoints.

A value of PENDING can mean one of the following:

  • The transfer intent has not yet been processed by the authorization engine (authorization_decision is "null"). This is the initial state of all transfer intents.

  • The transfer intent was processed and approved by the authorization engine (authorization_decision is "approved"), but has not yet been processed by the transfer creation processor.

  • The transfer intent was processed by the authorization engine and was declined (authorization_decision is "declined") due to insufficient funds (authorization_decision_rationale.code is "NSF"). If this is the case, the end user can retry the transfer intent up to three times. The transfer intent status will remain as "PENDING" throughout the retry intents. After three unsuccessful retries, the transfer intent status will be "FAILED".

Transfer UI best practices

While transfer UI provides a Nacha-compliant UI for your transfers, to maximize conversion, it is recommended to still provide context in your own app to your end users about the transfer. We recommend that your app implement a UI where the customer selects or confirms the transfer amount and, if applicable, the funds source or destination. To maximize user confidence, your app should also provide a post-Link success pane confirming the transfer details, including amount and effective date.

Sample app code

For a real-life example of an app that incorporates Transfer UI, see the Node-based Plaid Pattern Transfer sample app. Pattern Transfer is a sample subscriptions payment app that enables ACH bank transfers. The Transfer UI code can be found in transfers.js

Troubleshooting transfers

The onExit callback is called

If the onExit callback is called, the Link session failed to link an account. The transfer intent could not be initiated.

onSuccess is called, but the transfer intent is incomplete

The onSuccess callback is not an indication of a successful transfer creation or a successful transfer (i.e., funds movement). It only indicates the successful linking of an account. To fully diagnose incomplete transfer intents (i.e., when the transfer_status field in the metadata object returned by onSuccess is incomplete), call the /transfer/intent/get endpoint and pass in the corresponding transfer intent ID as an argument. Information about the transfer intent can be found in the status, failure_reason, authorization_decision, and authorization_decision_rationale fields in the response.

Network errors or institution connection issues

Network errors or institution connection issues can also result in incomplete transfer intents. In such cases, generate a new Link token using the existing access_token and invoke Transfer UI to allow the end user to attempt the transfer intent again.

api products income

Income

API reference for Income endpoints and webhooks

Verify a user's income via payroll or bank account data.

Endpoints
/credit/bank_income/getRetrieve information from the bank accounts used for income verification
/credit/bank_income/pdf/getRetrieve information from the bank accounts used for income verification in PDF format
/credit/bank_income/refreshRefresh a user's bank income information
/credit/bank_income/webhook/updateSubscribe and unsubscribe to proactive notifications for a user's income profile
/credit/payroll_income/getRetrieve information from the pay stubs or tax forms used for income verification
/credit/payroll_income/precheckCheck digital income verification eligibility and optimize conversion
/credit/payroll_income/risk_signals/getAnalyze uploaded income documents for indications of potential fraud
/credit/employment/get(Beta) Retrieve employment information about the end user
/credit/sessions/getGet Link session metadata and results for the end user
/user/createCreate a user for use with the income verification product
See also
/sandbox/income/fire_webhookManually fire an Income webhook (Sandbox only)
Webhooks
INCOME_VERIFICATIONIncome verification has completed
INCOME_VERIFICATION_RISK_SIGNALSRisk evaluation of user-uploaded documents has completed
BANK_INCOME_REFRESH_UPDATEA change to user's income has been detected
BANK_INCOME_REFRESH_COMPLETEThe refreshed report has finished generating

Endpoints

/credit/bank_income/get

Retrieve information from the bank accounts used for income verification

/credit/bank_income/get returns the bank income report(s) for a specified user.

credit/bank_income/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
user_token
string
The user token associated with the User data is being requested for.
options
object
An optional object for /credit/bank_income/get request options.
count
integer
How many Bank Income Reports should be fetched. Multiple reports may be available if the report has been re-created or refreshed. If more than one report is available, the most recent reports will be returned first.

Default: 1
Select Language
1const request: CreditBankIncomeGetRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3  options: {
4    count: 1,
5  },
6};
7
8try {
9  const response = await client.creditBankIncomeGet(request);
10} catch (error) {
11  // handle error
12}
credit/bank_income/get

Response fields and example

bank_income
[object]
bank_income_id
string
The unique identifier associated with the Bank Income Report.
generated_time
string
The time when the Bank Income Report was generated.

Format: date-time
days_requested
integer
The number of days requested by the customer for the Bank Income Report.
items
[object]
The list of Items in the report along with the associated metadata about the Item.
bank_income_accounts
[object]
The Item's accounts that have Bank Income data.
account_id
string
Plaid's unique identifier for the account.
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the bank account.
official_name
nullablestring
The official name of the bank account.
subtype
string
Valid account subtypes for depository accounts. For a list containing descriptions of each subtype, see Account schemas.

Possible values: checking, savings, hsa, cd, money market, paypal, prepaid, cash management, ebt, all
type
string
The account type. This will always be depository.

Possible values: depository
owners
[object]
Data returned by the financial institution about the account owner or owners. Identity information is optional, so field may return an empty array.
names
[string]
A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders.
If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.
phone_numbers
[object]
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
string
The phone number.
primary
boolean
When true, identifies the phone number as the primary number on an account.
type
string
The type of phone number.

Possible values: home, work, office, mobile, mobile1, other
emails
[object]
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
string
The email address.
primary
boolean
When true, identifies the email address as the primary email on an account.
type
string
The type of email account as described by the financial institution.

Possible values: primary, secondary, other
addresses
[object]
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
object
Data about the components comprising an address.
city
nullablestring
The full city name
region
nullablestring
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
nullablestring
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code
primary
boolean
When true, identifies the address as the primary address on an account.
bank_income_sources
[object]
The income sources for this Item. Each entry in the array is a single income source.
income_source_id
string
A unique identifier for an income source.
income_description
string
The most common name or original description for the underlying income transactions.
income_category
string
The income category. Note that the CASH value has been deprecated and is used only for existing legacy implementations. It has been replaced by the new categories CASH_DEPOSIT (representing cash or check deposits) and TRANSFER_FROM_APPLICATION (representing cash transfers originating from apps, such as Zelle or Venmo).

Possible values: SALARY, UNEMPLOYMENT, CASH, GIG_ECONOMY, RENTAL, CHILD_SUPPORT, MILITARY, RETIREMENT, LONG_TERM_DISABILITY, BANK_INTEREST, CASH_DEPOSIT, TRANSFER_FROM_APPLICATION, TAX_REFUND, BENEFIT_OTHER, OTHER
account_id
string
Plaid's unique identifier for the account.
start_date
string
Minimum of all dates within the specific income sources in the user's bank account for days requested by the client. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
end_date
string
Maximum of all dates within the specific income sources in the user’s bank account for days requested by the client. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
pay_frequency
string
The income pay frequency.

Possible values: WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY, DAILY, UNKNOWN
total_amount
number
Total amount of earnings in the user’s bank account for the specific income source for days requested by the client.
transaction_count
integer
Number of transactions for the income source within the start and end date.
historical_summary
[object]
total_amount
deprecatednumber
Total amount of earnings for the income source(s) of the user for the month in the summary. This may return an incorrect value if the summary includes income sources in multiple currencies. Please use total_amounts instead.
iso_currency_code
deprecatednullablestring
The ISO 4217 currency code of the amount or balance. Please use total_amounts instead.
unofficial_currency_code
deprecatednullablestring
The unofficial currency code associated with the amount or balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. Please use total_amounts instead.
total_amounts
[object]
Total amount of earnings for the income source(s) of the user for the month in the summary. This can contain multiple amounts, with each amount denominated in one unique currency.
amount
number
Value of amount with up to 2 decimal places.
iso_currency_code
nullablestring
The ISO 4217 currency code of the amount or balance.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the amount or balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
start_date
string
The start date of the period covered in this monthly summary. This date will be the first day of the month, unless the month being covered is a partial month because it is the first month included in the summary and the date range being requested does not begin with the first day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
end_date
string
The end date of the period included in this monthly summary. This date will be the last day of the month, unless the month being covered is a partial month because it is the last month included in the summary and the date range being requested does not end with the last day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
transactions
[object]
amount
number
The settled value of the transaction, denominated in the transactions's currency as stated in iso_currency_code or unofficial_currency_code. Positive values when money moves out of the account; negative values when money moves in. For example, credit card purchases are positive; credit card payment, direct deposits, and refunds are negative.
date
string
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
name
string
The merchant name or transaction description.
original_description
nullablestring
The string returned by the financial institution to describe the transaction.
pending
boolean
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.
transaction_id
string
The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive.
check_number
nullablestring
The check number of the transaction. This field is only populated for check transactions.
iso_currency_code
nullablestring
The ISO 4217 currency code of the amount or balance.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the amount or balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
last_updated_time
string
The time when this Item's data was last retrieved from the financial institution.

Format: date-time
institution_id
string
The unique identifier of the institution associated with the Item.
institution_name
string
The name of the institution associated with the Item.
item_id
string
The unique identifier for the Item.
bank_income_summary
object
Summary for bank income across all income sources and items (max history of 730 days).
total_amount
deprecatednumber
Total amount of earnings across all the income sources in the end user's Items for the days requested by the client. This may return an incorrect value if the summary includes income sources in multiple currencies. Please use total_amounts instead.
iso_currency_code
deprecatednullablestring
The ISO 4217 currency code of the amount or balance. Please use total_amounts instead.
unofficial_currency_code
deprecatednullablestring
The unofficial currency code associated with the amount or balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. Please use total_amounts instead.
total_amounts
[object]
Total amount of earnings across all the income sources in the end user's Items for the days requested by the client. This can contain multiple amounts, with each amount denominated in one unique currency.
amount
number
Value of amount with up to 2 decimal places.
iso_currency_code
nullablestring
The ISO 4217 currency code of the amount or balance.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the amount or balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
start_date
string
The earliest date within the days requested in which all income sources identified by Plaid appear in a user's account. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
end_date
string
The latest date in which all income sources identified by Plaid appear in the user's account. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
income_sources_count
integer
Number of income sources per end user.
income_categories_count
integer
Number of income categories per end user.
income_transactions_count
integer
Number of income transactions per end user.
historical_summary
[object]
total_amount
deprecatednumber
Total amount of earnings for the income source(s) of the user for the month in the summary. This may return an incorrect value if the summary includes income sources in multiple currencies. Please use total_amounts instead.
iso_currency_code
deprecatednullablestring
The ISO 4217 currency code of the amount or balance. Please use total_amounts instead.
unofficial_currency_code
deprecatednullablestring
The unofficial currency code associated with the amount or balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. Please use total_amounts instead.
total_amounts
[object]
Total amount of earnings for the income source(s) of the user for the month in the summary. This can contain multiple amounts, with each amount denominated in one unique currency.
amount
number
Value of amount with up to 2 decimal places.
iso_currency_code
nullablestring
The ISO 4217 currency code of the amount or balance.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the amount or balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
start_date
string
The start date of the period covered in this monthly summary. This date will be the first day of the month, unless the month being covered is a partial month because it is the first month included in the summary and the date range being requested does not begin with the first day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
end_date
string
The end date of the period included in this monthly summary. This date will be the last day of the month, unless the month being covered is a partial month because it is the last month included in the summary and the date range being requested does not end with the last day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
transactions
[object]
amount
number
The settled value of the transaction, denominated in the transactions's currency as stated in iso_currency_code or unofficial_currency_code. Positive values when money moves out of the account; negative values when money moves in. For example, credit card purchases are positive; credit card payment, direct deposits, and refunds are negative.
date
string
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
name
string
The merchant name or transaction description.
original_description
nullablestring
The string returned by the financial institution to describe the transaction.
pending
boolean
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.
transaction_id
string
The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive.
check_number
nullablestring
The check number of the transaction. This field is only populated for check transactions.
iso_currency_code
nullablestring
The ISO 4217 currency code of the amount or balance.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the amount or balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
warnings
[object]
If data from the Bank Income report was unable to be retrieved, the warnings will contain information about the error that caused the data to be incomplete.
warning_type
string
The warning type which will always be BANK_INCOME_WARNING.

Possible values: BANK_INCOME_WARNING
warning_code
string
The warning code identifies a specific kind of warning. IDENTITY_UNAVAILABLE: Unable to extract identity for the Item TRANSACTIONS_UNAVAILABLE: Unable to extract transactions for the Item ITEM_UNAPPROVED: User exited flow before giving permission to share data for the Item REPORT_DELETED: Report deleted due to customer or consumer request DATA_UNAVAILABLE: No relevant data was found for the Item

Possible values: IDENTITY_UNAVAILABLE, TRANSACTIONS_UNAVAILABLE, ITEM_UNAPPROVED, REPORT_DELETED, DATA_UNAVAILABLE
cause
object
An error object and associated item_id used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INTERNAL_SERVER_ERROR, INSUFFICIENT_CREDENTIALS, ITEM_LOCKED, USER_SETUP_REQUIRED, COUNTRY_NOT_SUPPORTED, INSTITUTION_DOWN, INSTITUTION_NO_LONGER_SUPPORTED, INSTITUTION_NOT_RESPONDING, INVALID_CREDENTIALS, INVALID_MFA, INVALID_SEND_METHOD, ITEM_LOGIN_REQUIRED, MFA_NOT_SUPPORTED, NO_ACCOUNTS, ITEM_NOT_SUPPORTED, ACCESS_NOT_GRANTED
error_code
string
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. Error fields will be null if no error has occurred.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action. This may change over time and is not safe for programmatic use.
item_id
string
The item_id of the Item associated with this warning.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "LhQf0THi8SH1yJm",
3  "bank_income": [
4    {
5      "bank_income_id": "abc123",
6      "generated_time": "2022-01-31T22:47:53Z",
7      "days_requested": 90,
8      "items": [
9        {
10          "last_updated_time": "2022-01-31T22:47:53Z",
11          "institution_id": "ins_0",
12          "institution_name": "Plaid Bank",
13          "item_id": "“eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6”",
14          "bank_income_accounts": [
15            {
16              "account_id": "“GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9”",
17              "mask": "8888",
18              "name": "Plaid Checking Account",
19              "official_name": "Plaid Checking Account",
20              "type": "depository",
21              "subtype": "checking",
22              "owners": [
23                {
24                  "addresses": [
25                    {
26                      "data": {
27                        "city": "Malakoff",
28                        "country": "US",
29                        "postal_code": "14236",
30                        "region": "NY",
31                        "street": "2992 Cameron Road"
32                      },
33                      "primary": true
34                    },
35                    {
36                      "data": {
37                        "city": "San Matias",
38                        "country": "US",
39                        "postal_code": "93405-2255",
40                        "region": "CA",
41                        "street": "2493 Leisure Lane"
42                      },
43                      "primary": false
44                    }
45                  ],
46                  "emails": [
47                    {
48                      "data": "accountholder0@example.com",
49                      "primary": true,
50                      "type": "primary"
51                    },
52                    {
53                      "data": "accountholder1@example.com",
54                      "primary": false,
55                      "type": "secondary"
56                    },
57                    {
58                      "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
59                      "primary": false,
60                      "type": "other"
61                    }
62                  ],
63                  "names": [
64                    "Alberta Bobbeth Charleson"
65                  ],
66                  "phone_numbers": [
67                    {
68                      "data": "1112223333",
69                      "primary": false,
70                      "type": "home"
71                    },
72                    {
73                      "data": "1112224444",
74                      "primary": false,
75                      "type": "work"
76                    },
77                    {
78                      "data": "1112225555",
79                      "primary": false,
80                      "type": "mobile"
81                    }
82                  ]
83                }
84              ]
85            }
86          ],
87          "bank_income_sources": [
88            {
89              "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",
90              "income_source_id": "“f17efbdd-caab-4278-8ece-963511cd3d51”",
91              "income_description": "“PLAID_INC_DIRECT_DEP_PPD”",
92              "income_category": "SALARY",
93              "start_date": "2021-11-15",
94              "end_date": "2022-01-15",
95              "pay_frequency": "MONTHLY",
96              "total_amount": 300,
97              "transaction_count": 1,
98              "historical_summary": [
99                {
100                  "start_date": "2021-11-02",
101                  "end_date": "2021-11-30",
102                  "total_amount": 100,
103                  "iso_currency_code": "USD",
104                  "unofficial_currency_code": null,
105                  "total_amounts": [
106                    {
107                      "amount": 100,
108                      "iso_currency_code": "USD",
109                      "unofficial_currency_code": null
110                    }
111                  ],
112                  "transactions": [
113                    {
114                      "amount": -100,
115                      "date": "2021-11-15",
116                      "name": "“PLAID_INC_DIRECT_DEP_PPD”",
117                      "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",
118                      "pending": false,
119                      "transaction_id": "6RddrWNwE1uM63Ex5GKLhzlBl76aAZfgzlQNm",
120                      "check_number": null,
121                      "iso_currency_code": "USD",
122                      "unofficial_currency_code": null
123                    }
124                  ]
125                },
126                {
127                  "start_date": "2021-12-01",
128                  "end_date": "2021-12-31",
129                  "total_amount": 100,
130                  "iso_currency_code": "USD",
131                  "unofficial_currency_code": null,
132                  "total_amounts": [
133                    {
134                      "amount": 100,
135                      "iso_currency_code": "USD",
136                      "unofficial_currency_code": null
137                    }
138                  ],
139                  "transactions": [
140                    {
141                      "amount": -100,
142                      "date": "2021-12-15",
143                      "name": "“PLAID_INC_DIRECT_DEP_PPD”",
144                      "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",
145                      "pending": false,
146                      "transaction_id": "7BddrWNwE1uM63Ex5GKLhzlBl82aAZfgzlCBl",
147                      "check_number": null,
148                      "iso_currency_code": "USD",
149                      "unofficial_currency_code": null
150                    }
151                  ]
152                },
153                {
154                  "start_date": "2022-01-01",
155                  "end_date": "2021-01-31",
156                  "total_amount": 100,
157                  "iso_currency_code": "USD",
158                  "unofficial_currency_code": null,
159                  "total_amounts": [
160                    {
161                      "amount": 100,
162                      "iso_currency_code": "USD",
163                      "unofficial_currency_code": null
164                    }
165                  ],
166                  "transactions": [
167                    {
168                      "amount": -100,
169                      "date": "2022-01-31",
170                      "name": "“PLAID_INC_DIRECT_DEP_PPD”",
171                      "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",
172                      "pending": false,
173                      "transaction_id": "9FddrWNwE1uM95Ex5GKLhzlBl76aAZfgzlNQr",
174                      "check_number": null,
175                      "iso_currency_code": "USD",
176                      "unofficial_currency_code": null
177                    }
178                  ]
179                }
180              ]
181            }
182          ]
183        }
184      ],
185      "bank_income_summary": {
186        "total_amount": 300,
187        "iso_currency_code": "USD",
188        "unofficial_currency_code": null,
189        "total_amounts": [
190          {
191            "amount": 300,
192            "iso_currency_code": "USD",
193            "unofficial_currency_code": null
194          }
195        ],
196        "start_date": "2021-11-15",
197        "end_date": "2022-01-15",
198        "income_sources_count": 1,
199        "income_categories_count": 1,
200        "income_transactions_count": 1,
201        "historical_summary": [
202          {
203            "start_date": "2021-11-02",
204            "end_date": "2021-11-30",
205            "total_amount": 100,
206            "iso_currency_code": "USD",
207            "unofficial_currency_code": null,
208            "total_amounts": [
209              {
210                "amount": 100,
211                "iso_currency_code": "USD",
212                "unofficial_currency_code": null
213              }
214            ],
215            "transactions": [
216              {
217                "amount": -100,
218                "date": "2021-11-15",
219                "name": "“PLAID_INC_DIRECT_DEP_PPD”",
220                "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",
221                "pending": false,
222                "transaction_id": "6RddrWNwE1uM63Ex5GKLhzlBl76aAZfgzlQNm",
223                "check_number": null,
224                "iso_currency_code": "USD",
225                "unofficial_currency_code": null
226              }
227            ]
228          },
229          {
230            "start_date": "2021-12-01",
231            "end_date": "2021-12-31",
232            "total_amount": 100,
233            "iso_currency_code": "USD",
234            "unofficial_currency_code": null,
235            "total_amounts": [
236              {
237                "amount": 100,
238                "iso_currency_code": "USD",
239                "unofficial_currency_code": null
240              }
241            ],
242            "transactions": [
243              {
244                "amount": -100,
245                "date": "2021-12-15",
246                "name": "“PLAID_INC_DIRECT_DEP_PPD”",
247                "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",
248                "pending": false,
249                "transaction_id": "7BddrWNwE1uM63Ex5GKLhzlBl82aAZfgzlCBl",
250                "check_number": null,
251                "iso_currency_code": "USD",
252                "unofficial_currency_code": null
253              }
254            ]
255          },
256          {
257            "start_date": "2022-01-01",
258            "end_date": "2021-01-31",
259            "total_amount": 100,
260            "iso_currency_code": "USD",
261            "unofficial_currency_code": null,
262            "total_amounts": [
263              {
264                "amount": 100,
265                "iso_currency_code": "USD",
266                "unofficial_currency_code": null
267              }
268            ],
269            "transactions": [
270              {
271                "amount": -100,
272                "date": "2022-01-31",
273                "name": "“PLAID_INC_DIRECT_DEP_PPD”",
274                "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",
275                "pending": false,
276                "transaction_id": "9FddrWNwE1uM95Ex5GKLhzlBl76aAZfgzlNQr",
277                "check_number": null,
278                "iso_currency_code": "USD",
279                "unofficial_currency_code": null
280              }
281            ]
282          }
283        ]
284      },
285      "warnings": []
286    }
287  ]
288}
Was this helpful?

/credit/bank_income/pdf/get

Retrieve information from the bank accounts used for income verification in PDF format

/credit/bank_income/pdf/get returns the most recent bank income report for a specified user in PDF format.

credit/bank_income/pdf/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
user_token
requiredstring
The user token associated with the User data is being requested for.
Select Language
1const request: CreditBankIncomePDFGetRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3};
4
5try {
6  const response = await client.creditBankIncomePdfGet(request, {
7    responseType: 'arraybuffer',
8  });
9  const pdf = response.buffer.toString('base64');
10} catch (error) {
11  // handle error
12}
Response

This endpoint returns binary PDF data. View a sample Bank Income PDF.

/credit/bank_income/refresh

Refresh a user's bank income information

/credit/bank_income/refresh refreshes the bank income report data for a specific user.

credit/bank_income/refresh

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
user_token
requiredstring
The user token associated with the User data is being requested for.
options
object
An optional object for /credit/bank_income/refresh request options.
days_requested
integer
How many days of data to include in the refresh. If not specified, this will default to the days requested in the most recently generated bank income report for the user.
Select Language
1const request: CreditBankIncomeRefreshRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3  options: {
4    days_requested: 90,
5  },
6};
7
8try {
9  const response = await client.creditBankIncomeRefresh(request);
10} catch (error) {
11  // handle error
12}
credit/bank_income/refresh

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "LhQf0THi8SH1yJm"
3}
Was this helpful?

/credit/bank_income/webhook/update

Subscribe and unsubscribe to proactive notifications for a user's income profile

/credit/bank_income/webhook/update allows you to subscribe or unsubscribe a user for income webhook notifications.
If a user is subscribed, on significant changes to the user's income profile, you will receive a BANK_INCOME_REFRESH_UPDATE webhook, prompting you to refresh bank income data for the user.

credit/bank_income/webhook/update

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
user_token
requiredstring
The user token associated with the User data is being requested for.
enable_webhooks
requiredboolean
Whether the user should be enabled for proactive webhook notifications when their income changes
Select Language
1const request: CreditBankIncomeWebhookUpdateRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3  enable_webhooks: true,
4};
5
6try {
7  const response = await client.creditBankIncomeWebhookUpdateRequest(request);
8} catch (error) {
9  // handle error
10}
credit/bank_income/webhook/update

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "LhQf0THi8SH1yJm"
3}
Was this helpful?

/credit/payroll_income/get

Retrieve a user's payroll information

This endpoint gets payroll income information for a specific user, either as a result of the user connecting to their payroll provider or uploading a pay related document.

credit/payroll_income/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
user_token
string
The user token associated with the User data is being requested for.
Select Language
1const request: CreditPayrollIncomeGetRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3};
4
5try {
6  const response = await client.creditPayrollIncomeGet(request);
7} catch (error) {
8  // handle error
9}
credit/payroll_income/get

Response fields and example

items
[object]
Array of payroll items.
item_id
string
The item_id of the Item associated with this webhook, warning, or error
institution_id
string
The unique identifier of the institution associated with the Item.
institution_name
string
The name of the institution associated with the Item.
accounts
[object]
account_id
nullablestring
ID of the payroll provider account.
rate_of_pay
object
An object representing the rate at which an individual is paid.
pay_rate
nullablestring
The rate at which an employee is paid.

Possible values: ANNUAL, HOURLY, CONTRACT, WEEKLY, BI_WEEKLY, MONTHLY, SEMI_MONTHLY, DAILY, COMMISSION, OTHER, null
pay_amount
nullablenumber
The amount at which an employee is paid.

Format: double
pay_frequency
nullablestring
The frequency at which an individual is paid.

Possible values: DAILY, WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY, CONTRACT, QUARTERLY, SEMI_ANNUALLY, ANNUALLY, OTHER, null
payroll_income
[object]
account_id
nullablestring
ID of the payroll provider account.
pay_stubs
[object]
Array of pay stubs for the user.
deductions
object
An object with the deduction information found on a pay stub.
breakdown
[object]
current_amount
nullablenumber
Raw amount of the deduction

Format: double
description
nullablestring
Description of the deduction line item
iso_currency_code
nullablestring
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the line item. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
ytd_amount
nullablenumber
The year-to-date amount of the deduction

Format: double
total
object
An object representing the total deductions for the pay period
current_amount
nullablenumber
Raw amount of the deduction

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the line item. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
ytd_amount
nullablenumber
The year-to-date total amount of the deductions

Format: double
document_id
nullablestring
An identifier of the document referenced by the document metadata.
document_metadata
object
Object representing metadata pertaining to the document.
name
string
The name of the document.
document_type
nullablestring
The type of document.
PAYSTUB: A paystub.
BANK_STATEMENT: A bank statement.
US_TAX_W2: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee.
US_MILITARY_ERAS: An electronic Retirement Account Statement (eRAS) issued by the US military.
US_MILITARY_LES: A Leave and Earnings Statement (LES) issued by the US military.
US_MILITARY_CLES: A Civilian Leave and Earnings Statment (CLES) issued by the US military.
GIG: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type.
PLAID_GENERATED_PAYSTUB_PDF: Used to indicate that the PDF for the paystub was generated by Plaid.
NONE: Used to indicate that there is no underlying document for the data.
UNKNOWN: Document type could not be determined.

Possible values: UNKNOWN, PAYSTUB, BANK_STATEMENT, US_TAX_W2, US_MILITARY_ERAS, US_MILITARY_LES, US_MILITARY_CLES, GIG, PLAID_GENERATED_PAYSTUB_PDF, NONE
download_url
nullablestring
Signed URL to retrieve the underlying file. This download URL can only be used once and expires after two minutes. To generate a new download URL, call /credit/payroll_income/get again.
status
nullablestring
The processing status of the document.
PROCESSING_COMPLETE: The document was successfully processed.
DOCUMENT_ERROR: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted.
UNKNOWN or null: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager.

Possible values: UNKNOWN, PROCESSING_COMPLETE, DOCUMENT_ERROR, null
page_count
nullableinteger
The number of pages of the uploaded document (if available).
earnings
object
An object representing both a breakdown of earnings on a pay stub and the total earnings.
breakdown
[object]
canonical_description
nullablestring
Commonly used term to describe the earning line item.

Possible values: BONUS, COMMISSION, OVERTIME, PAID_TIME_OFF, REGULAR_PAY, VACATION, BASIC_ALLOWANCE_HOUSING, BASIC_ALLOWANCE_SUBSISTENCE, OTHER, null
current_amount
nullablenumber
Raw amount of the earning line item.

Format: double
description
nullablestring
Description of the earning line item.
hours
nullablenumber
Number of hours applicable for this earning.
iso_currency_code
nullablestring
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
rate
nullablenumber
Hourly rate applicable for this earning.

Format: double
unofficial_currency_code
nullablestring
The unofficial currency code associated with the line item. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
ytd_amount
nullablenumber
The year-to-date amount of the deduction.

Format: double
total
object
An object representing both the current pay period and year to date amount for an earning category.
current_amount
nullablenumber
Total amount of the earnings for this pay period.

Format: double
hours
nullablenumber
Total number of hours worked for this pay period.
iso_currency_code
nullablestring
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the security. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
ytd_amount
nullablenumber
The total year-to-date amount of the earnings.

Format: double
employee
object
Data about the employee.
address
object
Address on the pay stub.
city
nullablestring
The full city name.
country
nullablestring
The ISO 3166-1 alpha-2 country code.
postal_code
nullablestring
The postal code of the address.
region
nullablestring
The region or state. Example: "NC"
street
nullablestring
The full street address.
name
nullablestring
The name of the employee.
marital_status
nullablestring
Marital status of the employee - either SINGLE or MARRIED.

Possible values: SINGLE, MARRIED, null
taxpayer_id
object
Taxpayer ID of the individual receiving the paystub.
id_type
nullablestring
Type of ID, e.g. 'SSN'.
id_mask
nullablestring
ID mask; i.e. last 4 digits of the taxpayer ID.
employer
object
Information about the employer on the pay stub.
address
object
Address on the pay stub.
city
nullablestring
The full city name.
country
nullablestring
The ISO 3166-1 alpha-2 country code.
postal_code
nullablestring
The postal code of the address.
region
nullablestring
The region or state. Example: "NC"
street
nullablestring
The full street address.
name
nullablestring
The name of the employer on the pay stub.
net_pay
object
An object representing information about the net pay amount on the pay stub.
current_amount
nullablenumber
Raw amount of the net pay for the pay period.

Format: double
description
nullablestring
Description of the net pay.
iso_currency_code
nullablestring
The ISO-4217 currency code of the net pay. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the net pay. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
ytd_amount
nullablenumber
The year-to-date amount of the net pay.

Format: double
pay_period_details
object
Details about the pay period.
pay_amount
nullablenumber
The amount of the paycheck.

Format: double
distribution_breakdown
[object]
account_name
nullablestring
Name of the account for the given distribution.
bank_name
nullablestring
The name of the bank that the payment is being deposited to.
current_amount
nullablenumber
The amount distributed to this account.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the net pay. Always null if unofficial_currency_code is non-null.
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number.
type
nullablestring
Type of the account that the paystub was sent to (e.g. 'checking').
unofficial_currency_code
nullablestring
The unofficial currency code associated with the net pay. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
end_date
nullablestring
The date on which the pay period ended, in ISO 8601 format ("yyyy-mm-dd").

Format: date
gross_earnings
nullablenumber
Total earnings before tax/deductions.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the net pay. Always null if unofficial_currency_code is non-null.
pay_date
nullablestring
The date on which the pay stub was issued, in ISO 8601 format ("yyyy-mm-dd").

Format: date
pay_frequency
nullablestring
The frequency at which an individual is paid.

Possible values: UNKNOWN, WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY, null
pay_basis
string
The explicit pay basis on the paystub (if present).

Possible values: SALARY, HOURLY, COMMISSION
start_date
nullablestring
The date on which the pay period started, in ISO 8601 format ("yyyy-mm-dd").

Format: date
unofficial_currency_code
nullablestring
The unofficial currency code associated with the net pay. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
w2s
[object]
Array of tax form W-2s.
document_metadata
object
Object representing metadata pertaining to the document.
name
string
The name of the document.
document_type
nullablestring
The type of document.
PAYSTUB: A paystub.
BANK_STATEMENT: A bank statement.
US_TAX_W2: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee.
US_MILITARY_ERAS: An electronic Retirement Account Statement (eRAS) issued by the US military.
US_MILITARY_LES: A Leave and Earnings Statement (LES) issued by the US military.
US_MILITARY_CLES: A Civilian Leave and Earnings Statment (CLES) issued by the US military.
GIG: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type.
PLAID_GENERATED_PAYSTUB_PDF: Used to indicate that the PDF for the paystub was generated by Plaid.
NONE: Used to indicate that there is no underlying document for the data.
UNKNOWN: Document type could not be determined.

Possible values: UNKNOWN, PAYSTUB, BANK_STATEMENT, US_TAX_W2, US_MILITARY_ERAS, US_MILITARY_LES, US_MILITARY_CLES, GIG, PLAID_GENERATED_PAYSTUB_PDF, NONE
download_url
nullablestring
Signed URL to retrieve the underlying file. This download URL can only be used once and expires after two minutes. To generate a new download URL, call /credit/payroll_income/get again.
status
nullablestring
The processing status of the document.
PROCESSING_COMPLETE: The document was successfully processed.
DOCUMENT_ERROR: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted.
UNKNOWN or null: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager.

Possible values: UNKNOWN, PROCESSING_COMPLETE, DOCUMENT_ERROR, null
page_count
nullableinteger
The number of pages of the uploaded document (if available).
document_id
string
An identifier of the document referenced by the document metadata.
employer
object
Information about the employer on the pay stub.
address
object
Address on the pay stub.
city
nullablestring
The full city name.
country
nullablestring
The ISO 3166-1 alpha-2 country code.
postal_code
nullablestring
The postal code of the address.
region
nullablestring
The region or state. Example: "NC"
street
nullablestring
The full street address.
name
nullablestring
The name of the employer on the pay stub.
employee
object
Data about the employee.
address
object
Address on the pay stub.
city
nullablestring
The full city name.
country
nullablestring
The ISO 3166-1 alpha-2 country code.
postal_code
nullablestring
The postal code of the address.
region
nullablestring
The region or state. Example: "NC"
street
nullablestring
The full street address.
name
nullablestring
The name of the employee.
marital_status
nullablestring
Marital status of the employee - either SINGLE or MARRIED.

Possible values: SINGLE, MARRIED, null
taxpayer_id
object
Taxpayer ID of the individual receiving the paystub.
id_type
nullablestring
Type of ID, e.g. 'SSN'.
id_mask
nullablestring
ID mask; i.e. last 4 digits of the taxpayer ID.
tax_year
nullablestring
The tax year of the W2 document.
employer_id_number
nullablestring
An employee identification number or EIN.
wages_tips_other_comp
nullablestring
Wages from tips and other compensation.
federal_income_tax_withheld
nullablestring
Federal income tax withheld for the tax year.
social_security_wages
nullablestring
Wages from social security.
social_security_tax_withheld
nullablestring
Social security tax withheld for the tax year.
medicare_wages_and_tips
nullablestring
Wages and tips from medicare.
medicare_tax_withheld
nullablestring
Medicare tax withheld for the tax year.
social_security_tips
nullablestring
Tips from social security.
allocated_tips
nullablestring
Allocated tips.
box_9
nullablestring
Contents from box 9 on the W2.
dependent_care_benefits
nullablestring
Dependent care benefits.
nonqualified_plans
nullablestring
Nonqualified plans.
box_12
[object]
code
nullablestring
W2 Box 12 code.
amount
nullablestring
W2 Box 12 amount.
statutory_employee
nullablestring
Statutory employee.
retirement_plan
nullablestring
Retirement plan.
third_party_sick_pay
nullablestring
Third party sick pay.
other
nullablestring
Other.
state_and_local_wages
[object]
state
nullablestring
State associated with the wage.
employer_state_id_number
nullablestring
State identification number of the employer.
state_wages_tips
nullablestring
Wages and tips from the specified state.
state_income_tax
nullablestring
Income tax from the specified state.
local_wages_tips
nullablestring
Wages and tips from the locality.
local_income_tax
nullablestring
Income tax from the locality.
locality_name
nullablestring
Name of the locality.
form1099s
[object]
Array of tax form 1099s.
document_id
nullablestring
An identifier of the document referenced by the document metadata.
document_metadata
object
Object representing metadata pertaining to the document.
name
string
The name of the document.
document_type
nullablestring
The type of document.
PAYSTUB: A paystub.
BANK_STATEMENT: A bank statement.
US_TAX_W2: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee.
US_MILITARY_ERAS: An electronic Retirement Account Statement (eRAS) issued by the US military.
US_MILITARY_LES: A Leave and Earnings Statement (LES) issued by the US military.
US_MILITARY_CLES: A Civilian Leave and Earnings Statment (CLES) issued by the US military.
GIG: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type.
PLAID_GENERATED_PAYSTUB_PDF: Used to indicate that the PDF for the paystub was generated by Plaid.
NONE: Used to indicate that there is no underlying document for the data.
UNKNOWN: Document type could not be determined.

Possible values: UNKNOWN, PAYSTUB, BANK_STATEMENT, US_TAX_W2, US_MILITARY_ERAS, US_MILITARY_LES, US_MILITARY_CLES, GIG, PLAID_GENERATED_PAYSTUB_PDF, NONE
download_url
nullablestring
Signed URL to retrieve the underlying file. This download URL can only be used once and expires after two minutes. To generate a new download URL, call /credit/payroll_income/get again.
status
nullablestring
The processing status of the document.
PROCESSING_COMPLETE: The document was successfully processed.
DOCUMENT_ERROR: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted.
UNKNOWN or null: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager.

Possible values: UNKNOWN, PROCESSING_COMPLETE, DOCUMENT_ERROR, null
page_count
nullableinteger
The number of pages of the uploaded document (if available).
form_1099_type
string
Form 1099 Type

Possible values: FORM_1099_TYPE_UNKNOWN, FORM_1099_TYPE_MISC, FORM_1099_TYPE_K
recipient
object
An object representing a recipient used in both 1099-K and 1099-MISC tax documents.
address
object
Address on the pay stub.
city
nullablestring
The full city name.
country
nullablestring
The ISO 3166-1 alpha-2 country code.
postal_code
nullablestring
The postal code of the address.
region
nullablestring
The region or state. Example: "NC"
street
nullablestring
The full street address.
name
nullablestring
Name of recipient.
tin
nullablestring
Tax identification number of recipient.
account_number
nullablestring
Account number number of recipient.
facta_filing_requirement
nullablestring
Checked if FACTA is a filing requirement.

Possible values: CHECKED, NOT CHECKED
second_tin_exists
nullablestring
Checked if 2nd TIN exists.

Possible values: CHECKED, NOT CHECKED
payer
object
An object representing a payer used by 1099-MISC tax documents.
address
object
Address on the pay stub.
city
nullablestring
The full city name.
country
nullablestring
The ISO 3166-1 alpha-2 country code.
postal_code
nullablestring
The postal code of the address.
region
nullablestring
The region or state. Example: "NC"
street
nullablestring
The full street address.
name
nullablestring
Name of payer.
tin
nullablestring
Tax identification number of payer.
telephone_number
nullablestring
Telephone number of payer.
filer
object
An object representing a filer used by 1099-K tax documents.
address
object
Address on the pay stub.
city
nullablestring
The full city name.
country
nullablestring
The ISO 3166-1 alpha-2 country code.
postal_code
nullablestring
The postal code of the address.
region
nullablestring
The region or state. Example: "NC"
street
nullablestring
The full street address.
name
nullablestring
Name of filer.
tin
nullablestring
Tax identification number of filer.
type
nullablestring
One of the following values will be provided: Payment Settlement Entity (PSE), Electronic Payment Facilitator (EPF), Other Third Party

Possible values: Payment Settlement Entity (PSE), Electronic Payment Facilitator (EPF), Other Third Party
tax_year
nullablestring
Tax year of the tax form.
rents
nullablenumber
Amount in rent by payer.

Format: double
royalties
nullablenumber
Amount in royalties by payer.

Format: double
other_income
nullablenumber
Amount in other income by payer.

Format: double
federal_income_tax_withheld
nullablenumber
Amount of federal income tax withheld from payer.

Format: double
fishing_boat_proceeds
nullablenumber
Amount of fishing boat proceeds from payer.

Format: double
medical_and_healthcare_payments
nullablenumber
Amount of medical and healthcare payments from payer.

Format: double
nonemployee_compensation
nullablenumber
Amount of nonemployee compensation from payer.

Format: double
substitute_payments_in_lieu_of_dividends_or_interest
nullablenumber
Amount of substitute payments made by payer.

Format: double
payer_made_direct_sales_of_5000_or_more_of_consumer_products_to_buyer
nullablestring
Whether or not payer made direct sales over $5000 of consumer products.
crop_insurance_proceeds
nullablenumber
Amount of crop insurance proceeds.

Format: double
excess_golden_parachute_payments
nullablenumber
Amount of golden parachute payments made by payer.

Format: double
gross_proceeds_paid_to_an_attorney
nullablenumber
Amount of gross proceeds paid to an attorney by payer.

Format: double
section_409a_deferrals
nullablenumber
Amount of 409A deferrals earned by payer.

Format: double
section_409a_income
nullablenumber
Amount of 409A income earned by payer.

Format: double
state_tax_withheld
nullablenumber
Amount of state tax withheld of payer for primary state.

Format: double
state_tax_withheld_lower
nullablenumber
Amount of state tax withheld of payer for secondary state.

Format: double
payer_state_number
nullablestring
Primary state ID.
payer_state_number_lower
nullablestring
Secondary state ID.
state_income
nullablenumber
State income reported for primary state.

Format: double
state_income_lower
nullablenumber
State income reported for secondary state.

Format: double
transactions_reported
nullablestring
One of the values will be provided Payment card Third party network

Possible values: Payment card, Third party network
pse_name
nullablestring
Name of the PSE (Payment Settlement Entity).
pse_telephone_number
nullablestring
Formatted (XXX) XXX-XXXX. Phone number of the PSE (Payment Settlement Entity).
gross_amount
nullablenumber
Gross amount reported.

Format: double
card_not_present_transaction
nullablenumber
Amount in card not present transactions.

Format: double
merchant_category_code
nullablestring
Merchant category of filer.
number_of_payment_transactions
nullablestring
Number of payment transactions made.
january_amount
nullablenumber
Amount reported for January.

Format: double
february_amount
nullablenumber
Amount reported for February.

Format: double
march_amount
nullablenumber
Amount reported for March.

Format: double
april_amount
nullablenumber
Amount reported for April.

Format: double
may_amount
nullablenumber
Amount reported for May.

Format: double
june_amount
nullablenumber
Amount reported for June.

Format: double
july_amount
nullablenumber
Amount reported for July.

Format: double
august_amount
nullablenumber
Amount reported for August.

Format: double
september_amount
nullablenumber
Amount reported for September.

Format: double
october_amount
nullablenumber
Amount reported for October.

Format: double
november_amount
nullablenumber
Amount reported for November.

Format: double
december_amount
nullablenumber
Amount reported for December.

Format: double
primary_state
nullablestring
Primary state of business.
secondary_state
nullablestring
Secondary state of business.
primary_state_id
nullablestring
Primary state ID.
secondary_state_id
nullablestring
Secondary state ID.
primary_state_income_tax
nullablenumber
State income tax reported for primary state.

Format: double
secondary_state_income_tax
nullablenumber
State income tax reported for secondary state.

Format: double
status
nullableobject
Details about the status of the payroll item.
processing_status
nullablestring
Denotes the processing status for the verification.
UNKNOWN: The processing status could not be determined.
PROCESSING_COMPLETE: The processing has completed and the user has approved for sharing. The data is available to be retrieved.
PROCESSING: The verification is still processing. The data is not available yet.
FAILED: The processing failed to complete successfully.
APPROVAL_STATUS_PENDING: The processing has completed but the user has not yet approved the sharing of the data.

Possible values: UNKNOWN, PROCESSING_COMPLETE, PROCESSING, FAILED, APPROVAL_STATUS_PENDING
updated_at
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the Item was updated.

Format: date-time
error
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "items": [
3    {
4      "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
5      "institution_id": "ins_92",
6      "institution_name": "ADP",
7      "accounts": [
8        {
9          "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",
10          "rate_of_pay": {
11            "pay_amount": 100000,
12            "pay_rate": "ANNUAL"
13          },
14          "pay_frequency": "BIWEEKLY"
15        }
16      ],
17      "payroll_income": [
18        {
19          "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",
20          "pay_stubs": [
21            {
22              "deductions": {
23                "breakdown": [
24                  {
25                    "current_amount": 123.45,
26                    "description": "taxes",
27                    "iso_currency_code": "USD",
28                    "unofficial_currency_code": null,
29                    "ytd_amount": 246.9
30                  }
31                ],
32                "total": {
33                  "current_amount": 123.45,
34                  "iso_currency_code": "USD",
35                  "unofficial_currency_code": null,
36                  "ytd_amount": 246.9
37                }
38              },
39              "document_metadata": {
40                "document_type": "PAYSTUB",
41                "name": "paystub.pdf",
42                "status": "PROCESSING_COMPLETE",
43                "download_url": null
44              },
45              "document_id": "2jkflanbd",
46              "earnings": {
47                "breakdown": [
48                  {
49                    "canonical_description": "REGULAR_PAY",
50                    "current_amount": 200.22,
51                    "description": "salary earned",
52                    "hours": 80,
53                    "iso_currency_code": "USD",
54                    "rate": null,
55                    "unofficial_currency_code": null,
56                    "ytd_amount": 400.44
57                  },
58                  {
59                    "canonical_description": "BONUS",
60                    "current_amount": 100,
61                    "description": "bonus earned",
62                    "hours": null,
63                    "iso_currency_code": "USD",
64                    "rate": null,
65                    "unofficial_currency_code": null,
66                    "ytd_amount": 100
67                  }
68                ],
69                "total": {
70                  "current_amount": 300.22,
71                  "hours": 160,
72                  "iso_currency_code": "USD",
73                  "unofficial_currency_code": null,
74                  "ytd_amount": 500.44
75                }
76              },
77              "employee": {
78                "address": {
79                  "city": "SAN FRANCISCO",
80                  "country": "US",
81                  "postal_code": "94133",
82                  "region": "CA",
83                  "street": "2140 TAYLOR ST"
84                },
85                "name": "ANNA CHARLESTON",
86                "marital_status": "SINGLE",
87                "taxpayer_id": {
88                  "id_type": "SSN",
89                  "id_mask": "3333"
90                }
91              },
92              "employer": {
93                "name": "PLAID INC",
94                "address": {
95                  "city": "SAN FRANCISCO",
96                  "country": "US",
97                  "postal_code": "94111",
98                  "region": "CA",
99                  "street": "1098 HARRISON ST"
100                }
101              },
102              "net_pay": {
103                "current_amount": 123.34,
104                "description": "TOTAL NET PAY",
105                "iso_currency_code": "USD",
106                "unofficial_currency_code": null,
107                "ytd_amount": 253.54
108              },
109              "pay_period_details": {
110                "distribution_breakdown": [
111                  {
112                    "account_name": "Big time checking",
113                    "bank_name": "bank of plaid",
114                    "current_amount": 176.77,
115                    "iso_currency_code": "USD",
116                    "mask": "1223",
117                    "type": "checking",
118                    "unofficial_currency_code": null
119                  }
120                ],
121                "end_date": "2020-12-15",
122                "gross_earnings": 4500,
123                "iso_currency_code": "USD",
124                "pay_amount": 1490.21,
125                "pay_date": "2020-12-15",
126                "pay_frequency": "BIWEEKLY",
127                "start_date": "2020-12-01",
128                "unofficial_currency_code": null
129              }
130            }
131          ],
132          "w2s": [
133            {
134              "allocated_tips": "1000",
135              "box_12": [
136                {
137                  "amount": "200",
138                  "code": "AA"
139                }
140              ],
141              "box_9": "box9",
142              "dependent_care_benefits": "1000",
143              "document_metadata": {
144                "document_type": "US_TAX_W2",
145                "download_url": null,
146                "name": "w_2.pdf",
147                "status": "PROCESSING_COMPLETE"
148              },
149              "document_id": "1pkflebk4",
150              "employee": {
151                "address": {
152                  "city": "San Francisco",
153                  "country": "US",
154                  "postal_code": "94103",
155                  "region": "CA",
156                  "street": "1234 Grand St"
157                },
158                "name": "Josie Georgia Harrison",
159                "marital_status": "SINGLE",
160                "taxpayer_id": {
161                  "id_type": "SSN",
162                  "id_mask": "1234"
163                }
164              },
165              "employer": {
166                "address": {
167                  "city": "New York",
168                  "country": "US",
169                  "postal_code": "10010",
170                  "region": "NY",
171                  "street": "456 Main St"
172                },
173                "name": "Acme Inc"
174              },
175              "employer_id_number": "12-1234567",
176              "federal_income_tax_withheld": "1000",
177              "medicare_tax_withheld": "1000",
178              "medicare_wages_and_tips": "1000",
179              "nonqualified_plans": "1000",
180              "other": "other",
181              "retirement_plan": "CHECKED",
182              "social_security_tax_withheld": "1000",
183              "social_security_tips": "1000",
184              "social_security_wages": "1000",
185              "state_and_local_wages": [
186                {
187                  "employer_state_id_number": "11111111111AAA",
188                  "local_income_tax": "200",
189                  "local_wages_and_tips": "200",
190                  "locality_name": "local",
191                  "state": "UT",
192                  "state_income_tax": "200",
193                  "state_wages_tips": "200"
194                }
195              ],
196              "statutory_employee": "CHECKED",
197              "tax_year": "2020",
198              "third_party_sick_pay": "CHECKED",
199              "wages_tips_other_comp": "1000"
200            }
201          ],
202          "form1099s": [
203            {
204              "april_amount": null,
205              "august_amount": null,
206              "card_not_present_transaction": null,
207              "crop_insurance_proceeds": 1000,
208              "december_amount": null,
209              "document_id": "mvMZ59Z2a5",
210              "document_metadata": {
211                "document_type": "US_TAX_1099_MISC",
212                "download_url": null,
213                "name": "form_1099_misc.pdf",
214                "status": "PROCESSING_COMPLETE"
215              },
216              "excess_golden_parachute_payments": 1000,
217              "feburary_amount": null,
218              "federal_income_tax_withheld": 1000,
219              "filer": {
220                "address": {
221                  "city": null,
222                  "country": null,
223                  "postal_code": null,
224                  "region": null,
225                  "street": null
226                },
227                "name": null,
228                "tin": null,
229                "type": null
230              },
231              "fishing_boat_proceeds": 1000,
232              "form_1099_type": "FORM_1099_TYPE_MISC",
233              "gross_amount": 1000,
234              "gross_proceeds_paid_to_an_attorney": 1000,
235              "january_amount": null,
236              "july_amount": null,
237              "june_amount": null,
238              "march_amount": null,
239              "may_amount": null,
240              "medical_and_healthcare_payments": 1000,
241              "merchant_category_code": null,
242              "nonemployee_compensation": 1000,
243              "november_amount": null,
244              "number_of_payment_transactions": null,
245              "october_amount": null,
246              "other_income": 1000,
247              "payer": {
248                "address": {
249                  "city": "SAN FRANCISCO",
250                  "country": "US",
251                  "postal_code": "94111",
252                  "region": "CA",
253                  "street": "1098 HARRISON ST"
254                },
255                "name": "PLAID INC",
256                "telephone_number": "(123)456-7890",
257                "tin": "12-3456789"
258              },
259              "payer_made_direct_sales_of_500_or_more_of_consumer_products_to_buyer": null,
260              "payer_state_number": "CA 12345",
261              "payer_state_number_lower": null,
262              "primary_state": null,
263              "primary_state_id": "CA 12345",
264              "primary_state_income_tax": 1000,
265              "pse_name": null,
266              "pse_telephone_number": null,
267              "recipient": {
268                "account_number": "45678",
269                "address": {
270                  "city": "SAN FRANCISCO",
271                  "country": "US",
272                  "postal_code": "94133",
273                  "region": "CA",
274                  "street": "2140 TAYLOR ST"
275                },
276                "facta_filing_requirement": "CHECKED",
277                "name": "Josie Georgia Harrison",
278                "second_tin_exists": "NOT CHECKED",
279                "tin": "12-3456789"
280              },
281              "rents": 1000,
282              "royalties": 1000,
283              "secondary_state": null,
284              "secondary_state_id": null,
285              "secondary_state_income_tax": null,
286              "section_409a_deferrals": 1000,
287              "section_409a_income": 1000,
288              "september_amount": null,
289              "state_income": 1000,
290              "state_income_lower": null,
291              "state_tax_withheld": 1000,
292              "state_tax_withheld_lower": null,
293              "substitute_payments_in_lieu_of_dividends_or_interest": null,
294              "tax_year": "2022",
295              "transactions_reported": null
296            }
297          ]
298        }
299      ],
300      "status": {
301        "processing_status": "PROCESSING_COMPLETE"
302      },
303      "updated_at": "2022-08-02T21:14:54Z"
304    }
305  ],
306  "request_id": "2pxQ59buGdsHRef"
307}
Was this helpful?

/credit/payroll_income/precheck

Check income verification eligibility and optimize conversion

/credit/payroll_income/precheck is an optional endpoint that can be called before initializing a Link session for income verification. It evaluates whether a given user is supportable by digital income verification. If the user is eligible for digital verification, that information will be associated with the user token, and in this way will generate a Link UI optimized for the end user and their specific employer. If the user cannot be confirmed as eligible, the user can still use the income verification flow, but they may be required to manually upload a paystub to verify their income.
While all request fields are optional, providing employer data will increase the chance of receiving a useful result.
When testing in Sandbox, you can control the results by providing special test values in the employer and access_tokens fields. employer_good and employer_bad will result in HIGH and LOW confidence values, respectively. employer_multi will result in a HIGH confidence with multiple payroll options. Likewise, access_good and access_bad will result in HIGH and LOW confidence values, respectively. Any other value for employer and access_tokens in Sandbox will result in UNKNOWN confidence.

credit/payroll_income/precheck

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
user_token
string
The user token associated with the User data is being requested for.
access_tokens
[string]
An array of access tokens corresponding to Items belonging to the user whose eligibility is being checked. Note that if the Items specified here are not already initialized with transactions, providing them in this field will cause these Items to be initialized with (and billed for) the Transactions product.
employer
object
Information about the end user's employer
name
string
The employer's name
address
object
Data about the components comprising an address.
city
string
The full city name
country
string
The ISO 3166-1 alpha-2 country code
postal_code
string
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
region
string
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
tax_id
string
The employer's tax id
url
string
The URL for the employer's public website
us_military_info
object
Data about military info in the income verification precheck.
is_active_duty
boolean
Is the user currently active duty in the US military
branch
string
If the user is currently serving in the US military, the branch of the military in which they are serving Valid values: 'AIR FORCE', 'ARMY', 'COAST GUARD', 'MARINES', 'NAVY', 'UNKNOWN'
payroll_institution
object
Information about the end user's payroll institution
name
string
The name of payroll institution
Select Language
1const request: CreditPayrollIncomePrecheckRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3  employer: {
4    name: 'Elm Publishing',
5    address: {
6      city: 'New York',
7      country: 'US',
8      postal_code: '10012',
9      region: 'NY',
10      street: '123 Main Street',
11    },
12    tax_id: '12-3456789',
13    url: 'https://elmpublishing.com',
14  },
15  us_military_info: {
16    is_active_duty: true,
17    branch: 'ARMY',
18  },
19};
20
21try {
22  const response = await client.creditPayrollIncomePrecheck(request);
23} catch (error) {
24  // handle error
25}
credit/payroll_income/precheck

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
confidence
string
The confidence that Plaid can support the user in the digital income verification flow instead of requiring a manual paystub upload. One of the following:
"HIGH": It is very likely that this user can use the digital income verification flow.
"LOW": It is unlikely that this user can use the digital income verification flow.
"UNKNOWN": It was not possible to determine if the user is supportable with the information passed.

Possible values: HIGH, LOW, UNKNOWN
1{
2  "request_id": "lMjeOeu9X1VUh1F",
3  "confidence": "HIGH"
4}
Was this helpful?

/credit/payroll_income/risk_signals/get

Retrieve fraud insights for a user's manually uploaded document(s).

/credit/payroll_income/risk_signals/get can be used as part of the Document Income flow to assess a user-uploaded document for signs of potential fraud or tampering. It returns a risk score for each uploaded document that indicates the likelihood of the document being fraudulent, in addition to details on the individual risk signals contributing to the score. /credit/payroll_income/risk_signals/get can be called at any time after the INCOME_VERIFICATION_RISK_SIGNALS webhook has been fired.
/credit/payroll_income/risk_signals/get is offered as an add-on to Document Income and is billed separately. To request access to this endpoint, submit a product access request or contact your Plaid account manager.

credit/payroll_income/risk_signals/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
user_token
string
The user token associated with the User data is being requested for.
Select Language
1const request: CreditPayrollIncomeRiskSignalsGetRequest = {
2  user_token: 'user-sandbox-dd4c42bd-4a81-4089-8146-40671e81dd12',
3};
4try {
5  const response = await client.creditPayrollIncomeRiskSignalsGet(request);
6} catch (error) {
7  // handle error
8}
credit/payroll_income/risk_signals/get

Response fields and example

items
[object]
Array of payroll items.
item_id
string
The item_id of the Item associated with this webhook, warning, or error
verification_risk_signals
[object]
Array of payroll income document authenticity data retrieved for each of the user's accounts.
account_id
nullablestring
ID of the payroll provider account.
single_document_risk_signals
[object]
Array of document metadata and associated risk signals per document
document_reference
object
Object containing metadata for the document
document_id
nullablestring
An identifier of the document referenced by the document metadata.
document_name
string
The name of the document
status
string
Status of a document for risk signal analysis

Possible values: PROCESSING, PROCESSING_COMPLETE, PROCESSING_ERROR, PASSWORD_PROTECTED, VIRUS_DETECTED
risk_signals
[object]
Array of attributes that indicate whether or not there is fraud risk with a document
type
nullablestring
The result from the risk signal check.

Possible values: FONT, MASKING, OVERLAID_TEXT, EDITED_TEXT, TEXT_COMPRESSION, ADDRESS_FORMAT_ANOMALY, DATE_FORMAT_ANOMALY, FONT_ANOMALY, NAME_FORMAT_ANOMALY, PDF_ALIGNMENT, BRUSH_DETECTION, METADATA_DATES_OUTSIDE_WINDOW, METADATA_DATES_INSIDE_WINDOW, METADATA_DATES_MISSING, METADATA_DATES_MATCH, ADOBE_FONTS, ANNOTATION_DATES, ANNOTATIONS, EDITED_WHILE_SCANNED, EXIF_DATA_MODIFIED, HIGH_USER_ACCESS, MALFORMED_DATE, QPDF, TEXT_LAYER_TEXT, TOUCHUP_TEXT, FLATTENED_PDF, BLACKLISTS, COPYCAT_IMAGE, COPYCAT_TEXT, REJECTED_CUSTOMER, TEMPLATES, SOFTWARE_BLACKLIST
field
nullablestring
The field which the risk signal was computed for
has_fraud_risk
nullableboolean
A flag used to quickly identify if the signal indicates that this field is authentic or fraudulent
institution_metadata
nullableobject
An object which contains additional metadata about the institution used to compute the verification attribute
item_id
string
The item_id of the Item associated with this webhook, warning, or error
expected_value
nullablestring
The expected value of the field, as seen on the document
actual_value
nullablestring
The derived value obtained in the risk signal calculation process for this field
signal_description
nullablestring
A human-readable explanation providing more detail into the particular risk signal
page_number
nullableinteger
The relevant page associated with the risk signal
risk_summary
object
A summary across all risk signals associated with a document
risk_score
nullablenumber
A number between 0 and 100, inclusive, where a score closer to 0 indicates a document is likely to be trustworthy and a score closer to 100 indicates a document is likely to be fraudulent
multi_document_risk_signals
[object]
Array of risk signals computed from a set of uploaded documents and the associated documents' metadata
document_references
[object]
Array of objects containing attributes that could indicate if a document is fraudulent
document_id
nullablestring
An identifier of the document referenced by the document metadata.
document_name
string
The name of the document
status
string
Status of a document for risk signal analysis

Possible values: PROCESSING, PROCESSING_COMPLETE, PROCESSING_ERROR, PASSWORD_PROTECTED, VIRUS_DETECTED
risk_signals
[object]
Array of attributes that indicate whether or not there is fraud risk with a set of documents
type
nullablestring
The result from the risk signal check.

Possible values: FONT, MASKING, OVERLAID_TEXT, EDITED_TEXT, TEXT_COMPRESSION, ADDRESS_FORMAT_ANOMALY, DATE_FORMAT_ANOMALY, FONT_ANOMALY, NAME_FORMAT_ANOMALY, PDF_ALIGNMENT, BRUSH_DETECTION, METADATA_DATES_OUTSIDE_WINDOW, METADATA_DATES_INSIDE_WINDOW, METADATA_DATES_MISSING, METADATA_DATES_MATCH, ADOBE_FONTS, ANNOTATION_DATES, ANNOTATIONS, EDITED_WHILE_SCANNED, EXIF_DATA_MODIFIED, HIGH_USER_ACCESS, MALFORMED_DATE, QPDF, TEXT_LAYER_TEXT, TOUCHUP_TEXT, FLATTENED_PDF, BLACKLISTS, COPYCAT_IMAGE, COPYCAT_TEXT, REJECTED_CUSTOMER, TEMPLATES, SOFTWARE_BLACKLIST
field
nullablestring
The field which the risk signal was computed for
has_fraud_risk
nullableboolean
A flag used to quickly identify if the signal indicates that this field is authentic or fraudulent
institution_metadata
nullableobject
An object which contains additional metadata about the institution used to compute the verification attribute
item_id
string
The item_id of the Item associated with this webhook, warning, or error
expected_value
nullablestring
The expected value of the field, as seen on the document
actual_value
nullablestring
The derived value obtained in the risk signal calculation process for this field
signal_description
nullablestring
A human-readable explanation providing more detail into the particular risk signal
page_number
nullableinteger
The relevant page associated with the risk signal
error
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "items": [
3    {
4      "item_id": "testItemID",
5      "verification_risk_signals": [
6        {
7          "account_id": null,
8          "multi_document_risk_signals": [],
9          "single_document_risk_signals": [
10            {
11              "document_reference": {
12                "document_id": "lRepoQjxlJ1nz",
13                "document_name": "Paystub.pdf"
14              },
15              "risk_summary": {
16                "risk_score": 70
17              },
18              "risk_signals": [
19                {
20                  "actual_value": "0.00",
21                  "expected_value": "25.09",
22                  "field": null,
23                  "signal_description": null,
24                  "has_fraud_risk": true,
25                  "type": "MASKING",
26                  "page_number": 1,
27                  "institution_metadata": {
28                    "item_id": "testItemID"
29                  }
30                },
31                {
32                  "actual_value": null,
33                  "expected_value": null,
34                  "field": null,
35                  "signal_description": "Creation date and modification date do not match",
36                  "has_fraud_risk": true,
37                  "institution_metadata": null,
38                  "type": "METADATA_DATES_OUTSIDE_WINDOW",
39                  "page_number": 0
40                }
41              ]
42            }
43          ]
44        }
45      ]
46    }
47  ],
48  "request_id": "LhQf0THi8SH1yJm"
49}
Was this helpful?

/credit/employment/get

Retrieve a summary of an individual's employment information

/credit/employment/get returns a list of items with employment information from a user's payroll provider that was verified by an end user.

credit/employment/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
user_token
requiredstring
The user token associated with the User data is being requested for.
Select Language
1const request: CreditEmploymentGetRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3};
4
5try {
6  const response = await client.creditEmploymentGet(request);
7} catch (error) {
8  // handle error
9}
credit/employment/get

Response fields and example

items
[object]
Array of employment items.
item_id
string
The item_id of the Item associated with this webhook, warning, or error
employments
[object]
account_id
nullablestring
ID of the payroll provider account.
status
nullablestring
Current employment status.

Possible values: ACTIVE, INACTIVE, null
start_date
nullablestring
Start of employment in ISO 8601 format (YYYY-MM-DD).

Format: date
end_date
nullablestring
End of employment, if applicable. Provided in ISO 8601 format (YYY-MM-DD).

Format: date
employer
object
An object containing employer data.
name
nullablestring
Name of employer.
title
nullablestring
Current title of employee.
platform_ids
object
The object containing a set of ids related to an employee.
employee_id
nullablestring
The ID of an employee as given by their employer.
payroll_id
nullablestring
The ID of an employee as given by their payroll.
position_id
nullablestring
The ID of the position of the employee.
employee_type
nullablestring
The type of employment for the individual. "FULL_TIME": A full-time employee. "PART_TIME": A part-time employee. "CONTRACTOR": An employee typically hired externally through a contracting group. "TEMPORARY": A temporary employee. "OTHER": The employee type is not one of the above defined types.

Possible values: FULL_TIME, PART_TIME, CONTRACTOR, TEMPORARY, OTHER, null
last_paystub_date
nullablestring
The date of the employee's most recent paystub in ISO 8601 format (YYYY-MM-DD).

Format: date
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "items": [
3    {
4      "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
5      "employments": [
6        {
7          "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",
8          "status": "ACTIVE",
9          "start_date": "2020-01-01",
10          "end_date": null,
11          "employer": {
12            "name": "Plaid Inc"
13          },
14          "title": "Software Engineer",
15          "platform_ids": {
16            "employee_id": "1234567",
17            "position_id": "8888",
18            "payroll_id": "1234567"
19          },
20          "employee_type": "FULL_TIME",
21          "last_paystub_date": "2022-01-15"
22        }
23      ]
24    }
25  ],
26  "request_id": "LhQf0THi8SH1yJm"
27}
Was this helpful?

/credit/sessions/get

Retrieve Link sessions for your user

This endpoint can be used for your end users after they complete the Link flow. This endpoint returns a list of Link sessions that your user completed, where each session includes the results from the Link flow.
These results include details about the Item that was created and some product related metadata (showing, for example, whether the user finished the bank income verification step).

credit/sessions/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
user_token
requiredstring
The user token associated with the User data is being requested for.
Select Language
1const request: CreditSessionsGetRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3};
4
5try {
6  const response = await client.creditSessionsGet(request);
7} catch (error) {
8  // handle error
9}
credit/sessions/get

Response fields and example

sessions
[object]
A list of Link sessions for the user. Sessions will be sorted in reverse chronological order.
link_session_id
string
The unique identifier associated with the Link session. This identifier matches the link_session_id returned in the onSuccess/onExit callbacks.
session_start_time
string
The time when the Link session started

Format: date-time
results
object
The set of results for a Link session.
item_add_results
[object]
The set of Item adds for the Link session.
public_token
string
Returned once a user has successfully linked their Item.
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
string
The Plaid Institution ID associated with the Item.
bank_income_results
[object]
The set of bank income verifications for the Link session.
status
string
Status of the Bank Income Link session.
APPROVED: User has approved and verified their income
NO_DEPOSITS_FOUND: We attempted, but were unable to find any income in the connected account.
USER_REPORTED_NO_INCOME: The user explicitly indicated that they don't receive income in the connected account.
STARTED: The user began the bank income portion of the link flow.
INTERNAL_ERROR: The user encountered an internal error.

Possible values: APPROVED, NO_DEPOSITS_FOUND, USER_REPORTED_NO_INCOME
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
string
The Plaid Institution ID associated with the Item.
bank_employment_results
[object]
The set of bank employment verifications for the Link session.
status
string
Status of the Bank Employment Link session.
APPROVED: User has approved and verified their employment.
NO_EMPLOYMENTS_FOUND: We attempted, but were unable to find any employment in the connected account.
EMPLOYER_NOT_LISTED: The user explicitly indicated that they did not see their current or previous employer in the list of employer names found.
STARTED: The user began the bank income portion of the link flow.
INTERNAL_ERROR: The user encountered an internal error.

Possible values: APPROVED, NO_EMPLOYERS_FOUND, EMPLOYER_NOT_LISTED
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
string
The Plaid Institution ID associated with the Item.
payroll_income_results
[object]
The set of payroll income verifications for the Link session.
num_paystubs_retrieved
integer
The number of paystubs retrieved from a payroll provider.
num_w2s_retrieved
integer
The number of w2s retrieved from a payroll provider.
institution_id
string
The Plaid Institution ID associated with the Item.
institution_name
string
The Institution Name associated with the Item.
document_income_results
nullableobject
The details of a document income verification in Link
num_paystubs_uploaded
integer
The number of paystubs uploaded by the user.
num_w2s_uploaded
integer
The number of w2s uploaded by the user.
num_bank_statements_uploaded
integer
The number of bank statements uploaded by the user.
errors
[object]
The set of errors that occurred during the Link session.
error_type
string
A broad categorization of the error.
error_code
string
The particular error code.
error_message
string
A developer-friendly representation of the error code.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "Aim3b",
3  "sessions": [
4    {
5      "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171",
6      "results": {
7        "item_add_results": [
8          {
9            "public_token": "public-sandbox-5c224a01-8314-4491-a06f-39e193d5cddc",
10            "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
11            "institution_id": "ins_56"
12          }
13        ],
14        "bank_income_results": [
15          {
16            "status": "APPROVED",
17            "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
18            "institution_id": "ins_56"
19          }
20        ]
21      },
22      "session_start_time": "2022-09-30T23:40:30.946225Z"
23    },
24    {
25      "link_session_id": "f742cae8-31e4-49cc-a621-6cafbdb26fb9",
26      "results": {
27        "payroll_income_results": [
28          {
29            "num_paystubs_retrieved": 2,
30            "num_w2s_retrieved": 1,
31            "institution_id": "ins_92"
32          }
33        ]
34      },
35      "session_start_time": "2022-09-26T23:40:30.946225Z"
36    }
37  ]
38}
Was this helpful?

/user/create

Create user

This endpoint should be called for each of your end users before they begin a Plaid income flow. This provides you a single token to access all income data associated with the user. You should only create one per end user.
If you call the endpoint multiple times with the same client_user_id, the first creation call will succeed and the rest will fail with an error message indicating that the user has been created for the given client_user_id.
Ensure that you store the user_token along with your user's identifier in your database, as it is not possible to retrieve a previously created user_token.

user/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_user_id
requiredstring
A unique ID representing the end user. Maximum of 128 characters. Typically this will be a user ID number from your application. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Max length: 128
Min length: 1
Select Language
1const request: UserCreateRequest = {
2  client_user_id: 'c0e2c4ee-b763-4af5-cfe9-46a46bce883d'
3};
4
5try {
6  const response = await client.userCreate(request);
7} catch (error) {
8  // handle error
9}
user/create

Response fields and example

user_token
string
The user token associated with the User data is being requested for.
user_id
string
The Plaid user_id of the User associated with this webhook, warning, or error.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "user_token": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
3  "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
4  "request_id": "Aim3b"
5}
Was this helpful?

Webhooks

Income webhooks are sent to indicate when an income verification or document fraud risk evaluation has finished processing.

INCOME_VERIFICATION

Fired when the status of an income verification instance has changed. It will typically take several minutes for this webhook to fire after the end user has uploaded their documents in the Document Income flow.

webhook_type
string
"INCOME"
webhook_code
string
INCOME_VERIFICATION
item_id
string
The Item ID associated with the verification.
user_id
string
The Plaid user_id of the User associated with this webhook, warning, or error.
verification_status
string
VERIFICATION_STATUS_PROCESSING_COMPLETE: The income verification status processing has completed. If the user uploaded multiple documents, this webhook will fire when all documents have finished processing. Call the /credit/payroll_income/get endpoint and check the document metadata to see which documents were successfully parsed.
VERIFICATION_STATUS_PROCESSING_FAILED: A failure occurred when attempting to process the verification documentation.
VERIFICATION_STATUS_PENDING_APPROVAL: (deprecated) The income verification has been sent to the user for review.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "INCOME",
3  "webhook_code": "INCOME_VERIFICATION",
4  "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ",
5  "user_id": "9eaba3c2fdc916bc197f279185b986607dd21682a5b04eab04a5a03e8b3f3334",
6  "verification_status": "VERIFICATION_STATUS_PROCESSING_COMPLETE",
7  "environment": "production"
8}
Was this helpful?

INCOME_VERIFICATION_RISK_SIGNALS

Fired when risk signals have been processed for documents uploaded via Document Income. It will typically take a minute or two for this webhook to fire after the end user has uploaded their documents in the Document Income flow. Once this webhook has fired, /credit/payroll_income/risk_signals/get may then be called to determine whether the documents were successfully processed and to retrieve risk data.

webhook_type
string
"INCOME"
webhook_code
string
INCOME_VERIFICATION_RISK_SIGNALS
item_id
string
The Item ID associated with the verification.
user_id
string
The Plaid user_id of the User associated with this webhook, warning, or error.
risk_signals_status
string
RISK_SIGNALS_PROCESSING_COMPLETE: The income verification fraud detection processing has completed. If the user uploaded multiple documents, this webhook will fire when all documents have finished processing. Call the /credit/payroll_income/risk_signals/get endpoint to get all risk signal data.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "INCOME",
3  "webhook_code": "INCOME_VERIFICATION_RISK_SIGNALS",
4  "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ",
5  "user_id": "9eaba3c2fdc916bc197f279185b986607dd21682a5b04eab04a5a03e8b3f3334",
6  "status": "RISK_SIGNALS_PROCESSING_COMPLETE",
7  "environment": "production"
8}
Was this helpful?

BANK_INCOME_REFRESH_UPDATE

Fired when a change to the user's income is detected. You should call /credit/bank_income/refresh to get updated income data for the user

webhook_type
string
INCOME
webhook_code
string
BANK_INCOME_REFRESH_UPDATE
user_id
string
The user_id corresponding to the user the webhook has fired for.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "INCOME",
3  "webhook_code": "BANK_INCOME_REFRESH_UPDATE",
4  "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "environment": "production"
6}
Was this helpful?

BANK_INCOME_REFRESH_COMPLETE

Fired when a refreshed bank income report has finished generating or failed to generate, triggered by calling /credit/bank_income/refresh.

webhook_type
string
INCOME
webhook_code
string
BANK_INCOME_REFRESH_COMPLETE
user_id
string
The user_id corresponding to the user the webhook has fired for.
result
string
The result of the bank income refresh report generation
SUCCESS: The refreshed report was successfully generated and can be retrieved via /credit/bank_income/get.
FAILURE: The refreshed report failed to be generated

Possible values: SUCCESS, FAILURE
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "INCOME",
3  "webhook_code": "BANK_INCOME_REFRESH_COMPLETE",
4  "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "result": "SUCCESS",
6  "environment": "production"
7}
Was this helpful?

transfer add to app

Add Transfer to your app

Intelligently process transfers between accounts

In this guide, we'll walk through how to use Transfer and Transfer UI to transfer funds between accounts.

Transfer UI allows a user to link an account using an intuitive interface to authorize a transfer. The first time a user uses Transfer UI, they will link a bank account and authorize the transfer of funds. After that, Transfer UI will only be used to authorize the transfer of funds for their already-linked bank account.

The Transfer product does not have a user interface and requires that you build your own NACHA-compliant user interface for users to authorize transfers. Users will go through Plaid's standard Link flow to link a bank account one time, and then you will use the Transfer product to move their funds afterwards.

You will normally use either Transfer UI or Transfer, but they can also be used together in the same app. For example, in a monthly subscriptions-based app you might initially use Transfer UI for your user to link their account and authorize their first payment, then use Transfer for the subsequent months so that the user does not have to be present to transfer their monthly payments.

Get Plaid API keys and complete application and company profile

If you don't already have one, you'll need to create a Plaid developer account. After creating your account, you can find your API keys under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your application profile and company profile on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the Plaid Portal. Your application profile and company profile must be completed before connecting to certain institutions in Production.

Install and initialize Plaid libraries

You can use our official server-side client libraries to connect to the Plaid API from your application:

Select group for content switcher
Select Language
1// Install via npm
2npm install --save plaid

After you've installed Plaid's client libraries, you can initialize them by passing in your client_id, secret, and the environment you wish to connect to (Sandbox or Production -- Transfer is not supported in the Development environment). This will make sure the client libraries pass along your client_id and secret with each request, and you won't need to explicitly include them in any other calls.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can obtain from the Dashboard. These code samples also demonstrate starting up a server commonly used in each framework (such as Express or Flask).

Select group for content switcher
Select Language
1// Using Express
2const express = require('express');
3const app = express();
4app.use(express.json());
5
6const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
7
8const configuration = new Configuration({
9  basePath: PlaidEnvironments.sandbox,
10  baseOptions: {
11    headers: {
12      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
13      'PLAID-SECRET': process.env.PLAID_SECRET,
14    },
15  },
16});
17
18const client = new PlaidApi(configuration);

Initiate Transfer without Transfer UI

Unlike Transfer UI, Transfer moves funds without a built in user interface that allows users to authorize transfers. If you are not using Transfer UI, you will need to build your own NACHA-compliant user interface for users to authorize transfers. The following steps will take place after your user has authorized an amount to be transferred from their bank.

Create a Payment Profile (optional)

Create a Payment Profile using /payment_profile/create and receive a payment_profile_token. Creating a payment profile is optional but is recommended to increase conversion if you are not using Transfer UI and are using Transfer as your only Plaid Product.

Create a Link token

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the Link documentation. Transfer UI works with Link to provide users with an interface to authorize ACH transfers.

Before initializing Link, you will need to create a new link_token on the server side of your application. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the /link/token/create endpoint. Then, on the client side of your application, you'll need to initialize Link with the link_token that you just created.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can obtain from the Dashboard.

If you have created a Payment Profile, provide the payment_profile_token in the transfer.payment_profile_token field and the user's phone number in the user.phone_number field.

Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9      phone_number: '123-456-7890',
10    },
11    transfer: {
12      payment_profile_token: paymentProfileToken,
13    },
14    client_name: 'Plaid Test App',
15    products: ['transfer'],
16    language: 'en',
17    webhook: 'https://webhook.example.com',
18    redirect_uri: 'https://domainname.com/oauth-page.html',
19    country_codes: ['US'],
20  };
21  try {
22    const createTokenResponse = await client.linkTokenCreate(request);
23    response.json(createTokenResponse.data);
24  } catch (error) {
25    // handle error
26  }
27});
1<head>
2  <title>Connect a bank</title>
3  <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
4</head>
1const linkHandler = Plaid.create({
2  token: (await $.post('/create_link_token')).link_token,
3  onSuccess: (public_token, metadata) => {
4    // Send the public_token to your app server.
5    $.post('/exchange_public_token', {
6      public_token: public_token,
7    });
8    if (metadata.transfer_status ==="COMPLETE") {
9    //   Get transfer_id from transfer/intent/get endpoint and save
10    //   transfer to datastore.
11    },
12  onExit: (err, metadata) => {
13    // Optionally capture when your user exited the Link flow.
14    // Storing this information can be helpful for support.
15  },
16  onEvent: (eventName, metadata) => {
17    // Optionally capture Link flow events, streamed through
18    // this callback as your users connect an Item to Plaid.
19  },
20});
21
22linkHandler.open();
(If not using a Payment Profile) Get a persistent access_token

This step is only necessary if not using a Payment Profile. If you are using one, proceed to Create a transfer authorization id.

Next, on the server side, we need to exchange our public_token for an access_token and item_id. The access_token will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the /item/public_token/exchange endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the access_token and item_id in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. The access_token will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via /item/remove. The access_token should be stored securely, and never in client-side code. A public_token is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

Select group for content switcher
Select Language
1app.post('/api/exchange_public_token', async function (
2  request,
3  response,
4  next,
5) {
6  const publicToken = request.body.public_token;
7  try {
8    const response = await client.itemPublicTokenExchange({
9      public_token: publicToken,
10    });
11
12    // These values should be saved to a persistent database and
13    // associated with the currently signed-in user
14    const accessToken = response.data.access_token;
15    const itemID = response.data.item_id;
16
17    res.json({ public_token_exchange: 'complete' });
18  } catch (error) {
19    // handle error
20  }
21});
Create a transfer authorization id

To get authorization to create a transfer and determine the transfer failure risk, call the /transfer/authorization/create endpoint with the following:

  • The user's payment_profile_token or access_token and the account_id (the account must be either a checking or savings account)

  • The amount (fund amount) you’re sending

  • type as credit if sending funds, or type as debit if receiving funds

  • ach_class as ppd for a personal account, or as ccd for a business account

  • user object with legal_name and other information (if you've specified ccd as the ach_class, you'll also need to specify the business’s name on the account within the user.legal_name parameter; if set to a person’s name it will be rejected).

Select Language
1const request: TransferAuthorizationCreateRequest = {
2  payment_profile_token: 'PAYMENT_PROFILE_TOKEN',
3  type: 'debit',
4  network: 'ach',
5  amount: '12.34',
6  ach_class: 'ppd',
7  user: {
8    legal_name: 'Anna Charleston',
9  },
10};
11
12try {
13  const response = await client.transferAuthorizationCreate(request);
14  const authorizationId = response.data.authorization.id;
15} catch (error) {
16  // handle error
17}

The response will contain an authorization object with details about the transfer authorization, including:

  • authorization.id: you'll need this to create the transfer in next step (this expires after 24 hours so you should persist this in a datastore)

  • authorization.decision: the decision from the authorization engine regarding the transfer. If this decision is "approved", you can proceed to the next step and create the transfer. If the decision is "declined", you will not be able to create the transfer (for more information on the decision and decision_rationale fields, see Transfer decision authorization).

1{
2  "authorization": {
3    "id": "560cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
4    "created": "2020-08-06T17:27:15Z",
5    "decision": "approved",
6    "decision_rationale": null,
7    "proposed_transfer": {
8      "ach_class": "ppd",
9      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
10      "type": "debit",
11      "user": {
12        "legal_name": "Anna Charleston",
13        "phone_number": "510-555-0128",
14        "email_address": "acharleston@email.com",
15        "address": {
16          "street": "100 Market Street",
17          "city": "San Francisco",
18          "region": "California",
19          "postal_code": "94103",
20          "country": "US"
21        }
22      },
23      "amount": "12.34",
24      "network": "ach",
25      "origination_account_id": "0123-4567-8901-2345-67890123"
26    }
27  },
28  "request_id": "saKrIBuEB9qJZno"
29}
Create the transfer

Create the transfer by calling the /transfer/create endpoint with the following:

  • The authorization_id of the transfer (returned from the previous step)

  • user’s payment_profile_token or access_token and account_id

  • amount you’re sending

  • type as debit or credit

  • ach_class (either ppd for a personal account or ccd for a business account)

  • user object with legal_name and other information (if you've specified ccd as the ach_class, you'll also need to specify the business’s name on the account within the user.legal_name parameter; if set to a person’s name it will be rejected).

  • If reprocessing a returned transfer, please note that the description field must be "Retry" to indicate that it's a retry of a previously returned transfer. You may retry a transfer up to 2 times, within 180 days of creating the original transfer. Only transfers that were returned with code R01 or R09 may be retried. For a full listing of ACH return codes, see Transfer errors.

Select Language
1const request: TransferCreateRequest = {
2  type: 'debit',
3  network: 'ach',
4  amount: '12.34',
5  description: 'payment',
6  ach_class: 'ppd',
7  user: {
8    legal_name: 'Anna Charleston',
9  },
10  payment_profile_token: paymentProfileToken,
11  authorization_id: '560cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
12};
13try {
14  const response = await client.transferCreate(request);
15  const transfer = response.data.transfer;
16} catch (error) {
17  // handle error
18}

Your transfer is now complete. In the response is a transfer object, which contains the details of the transfer you just created, including a status field. Possible values for the status are pending, posted, cancelled, failed, or reversed. Learn more about Transfer states to better understand these values. We recommend persisting the transfer_id in a datastore as you’ll need this when reconciling transactions or canceling a transaction. You can use this transfer_id going forward to call the /transfer/get endpoint to get a transfer's status, as we did above for the transfer we created with Transfer UI.

1{
2  "transfer": {
3    "id": "560cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
4    "ach_class": "ppd",
5    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
6    "type": "debit",
7    "user": {
8      "legal_name": "Anna Charleston",
9      "phone_number": "510-555-0128",
10      "email_address": "acharleston@email.com",
11      "address": {
12        "street": "100 Market Street",
13        "city": "San Francisco",
14        "region": "California",
15        "postal_code": "94103",
16        "country": "US"
17      }
18    },
19    "amount": "12.34",
20    "description": "A description of the transfer",
21    "created": "2020-08-06T17:27:15Z",
22    "status": "pending",
23    "network": "ach",
24    "cancellable": true,
25    "failure_reason": null,
26    "metadata": {
27      "key1": "value1",
28      "key2": "value2"
29    },
30    "origination_account_id": "0123-4567-8901-2345-67890123"
31  },
32  "request_id": "saKrIBuEB9qJZno"
33}

Link and Transfer UI

Link Customization

To use Transfer UI, in the Plaid Dashboard, create a new customization for Transfer UI with Account Select v2 ("ASv2") and the view behavior set to "Enabled for one account". This is the only view behavior supported by Transfer UI. You will use the Link customization name you set here when you create a Link token below.

Generate a transfer intent object

The first step to launch Transfer UI is to call the /transfer/intent/create endpoint. This endpoint generates a transfer intent object. Take special note of the id field returned in the transfer intent object and save it in your datastore. The value of this field is Plaid's unique identifier for the transfer intent object and can be used later to track the status of a transfer intent and retrieve data regarding the transfer you create with Transfer UI. This transfer intent ID will be used below when you create a Link token.

Select Language
1const request: TransferIntentCreateRequest = {
2  mode: 'PAYMENT'
3  amount: '12.34',
4  description: 'payment',
5  ach_class: 'ppd',
6  user: {
7    legal_name: 'Leslie Knope',
8  }
9};
10
11try {
12  const response = await client.transferIntentCreate(request);
13} catch (error) {
14  // handle error
15}
1{
2  "transfer_intent": {
3    "ach_class": "ppd",
4    "amount": "12.34",
5    "iso_currency_code": "USD",
6    "created": "2020-08-06T17:27:15Z",
7    "description": "payment",
8    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
9    "metadata": {
10      "key1": "value1",
11      "key2": "value2"
12    },
13    "mode": "PAYMENT",
14    "origination_account_id": "9853defc-e703-463d-86b1-dc0607a45359",
15    "status": "PENDING",
16    "user": {
17      "address": {
18        "street": "100 Market Street",
19        "city": "San Francisco",
20        "region": "CA",
21        "postal_code": "94103",
22        "country": "US"
23      },
24      "email_address": "lknope@email.com",
25      "legal_name": "Leslie Knope",
26      "phone_number": "123-456-7890"
27    }
28  },
29  "request_id": "saKrIBuEB9qJZno"
30}
Initialize Link with Transfer UI

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Transfer UI works with Link to provide users with an interface to authorize ACH transfers.

Before initializing Link, you will need to create a new link_token on the server side of your application. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the /link/token/create endpoint. Then, on the client side of your application, you'll need to initialize Link with the link_token that you just created.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can obtain from the Dashboard.

Call /link/token/create with the parameters shown in the code sample below. Note these parameters in particular:

  • "transfer" in the products array. Ensure that "transfer" is the only product being initialized.

  • A transfer object in the body of the create request. Within the transfer object, specify the transfer intent ID using the value of transfer intent id returned by the /transfer/intent/create call you made above.

  • The name of your Link customization that you created in the dashboard for Transfer UI.

Select Language
1// Using Express
2app.post('/api/create_link_token', async function (request, response) {
3  const configs = {
4    user: {
5      // This should correspond to a unique id for the current user.
6      client_user_id: 'user-id',
7    },
8    client_name: 'Plaid Test App',
9    products: [Products.Transfer],
10    language: 'en',
11    webhook: 'https://webhook.sample.com',
12    country_codes: ['US'],
13    transfer: {
14      intent_id: transferIntentId,
15    },
16    link_customization_name: process.env.LINK_CUSTOMIZATION_NAME,
17  };
18  try {
19    const createTokenResponse = await client.linkTokenCreate(configs);
20    response.json(createTokenResponse.data);
21  } catch (error) {
22    // handle error
23  }
24});
Retrieve the transfer_id and status

The Link onSuccess callback function provides a metadata object with a transfer_status field that will be either COMPLETE or INCOMPLETE. If INCOMPLETE, the transfer could not be completed. For help, see Troubleshooting transfers

If COMPLETE, your transfer has been completed, and you can follow the next steps to obtain the transfer_id and save it to your datastore because you’ll need this when reconciling transactions or canceling a transaction. You can use this transfer_id going forward to call the /transfer/get endpoint to get a transfer's status.

Using the transfer_intent_id saved earlier from the /transfer/intent/create call response, call the /transfer/intent/get endpoint.

Select Language
1const request: TransferIntentGetRequest = {
2  transfer_intent_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
3};
4
5try {
6  const response = await client.transferIntentGet(request);
7} catch (error) {
8  // handle error
9}

The example response is below. Retrieve the transfer_id and save your transfer in your datastore.

1{
2  "transfer_intent": {
3    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
4    "ach_class": "ppd",
5    "amount": "12.34",
6    "iso_currency_code": "USD",
7    "authorization_decision": "APPROVED",
8    "authorization_decision_rationale": null,
9    "created": "2019-12-09T17:27:15Z",
10    "description": "Desc",
11    "failure_reason": null,
12    "guarantee_decision": null,
13    "guarantee_decision_rationale": null,
14    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
15    "metadata": {
16      "key1": "value1",
17      "key2": "value2"
18    },
19    "mode": "DISBURSEMENT",
20    "origination_account_id": "9853defc-e703-463d-86b1-dc0607a45359",
21    "status": "SUCCEEDED",
22    "transfer_id": "590ecd12-1dcc-7eae-4ad6-c28d1ec90df2",
23    "user": {
24      "address": {
25        "street": "123 Main St.",
26        "city": "San Francisco",
27        "region": "California",
28        "postal_code": "94053",
29        "country": "US"
30      },
31      "email_address": "acharleston@email.com",
32      "legal_name": "Anne Charleston",
33      "phone_number": "510-555-0128"
34    }
35  },
36  "request_id": "saKrIBuEB9qJZno"
37}

Finally, obtain the status of your transfer by calling the /transfer/get endpoint with the transfer_id we just retrieved:

Select Language
1const request: TransferGetRequest = {
2  transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
3};
4try {
5  const response = await plaidClient.transferGet(request);
6  const transfer = response.data.transfer;
7} catch (error) {
8  // handle error
9}

Below is an example of the /transfer/get response, which includes the status of your transfer. Use this to update your transfer's status in the datastore.

1{
2  "transfer": {
3    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
4    "ach_class": "ppd",
5    "amount": "12.34",
6    "cancellable": true,
7    "created": "2020-08-06T17:27:15Z",
8    "description": "Desc",
9    "guarantee_decision": null,
10    "guarantee_decision_rationale": null,
11    "failure_reason": {
12      "ach_return_code": "R13",
13      "description": "Invalid ACH routing number"
14    },
15    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
16    "metadata": {
17      "key1": "value1",
18      "key2": "value2"
19    },
20    "network": "ach",
21    "origination_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
22    "status": "pending",
23    "type": "credit",
24    "iso_currency_code": "USD",
25    "user": {
26      "email_address": "acharleston@email.com",
27      "legal_name": "Anne Charleston",
28      "phone_number": "510-555-0128",
29      "address": {
30        "street": "123 Main St.",
31        "city": "San Francisco",
32        "region": "CA",
33        "postal_code": "94053",
34        "country": "US"
35      }
36    }
37  },
38  "request_id": "saKrIBuEB9qJZno"
39}
Subsequent transfers with Transfer UI

After the initial transfer with Transfer UI, for subsequent transfers users will no longer need to link a bank account. You will go through the same steps that you took for the first transfer, but with the following differences:

  • In the /transfer/intent/create call you must include an account_id field. This is the account_id of the bank account that the user has already linked.

  • In the /link/token/create call you must include the access_token field in the Link parameters. This is the access_token that you previously saved in your datastore, which is associated with the item that was created the first time you launched Link and Transfer UI. Launching Link with an access token will bypass the account linking flow and move the user directly to the Transfer UI interface to authorize their transfer.

Sample app code

For a real-life example of an app that incorporates both Transfer and Transfer UI, see the Node-based Plaid Pattern Transfer sample app. Pattern Transfer is a sample subscriptions payment app that enables ACH bank transfers.

Next steps

Once Transfer and Transfer UI are implemented in your app, see Reconciling Transfers and Sweeping Funds to learn about how to reconcile your transfers and how Plaid sweeps funds.

If you're ready to launch to Production, see the Launch checklist.

api products transfer

Transfer

API reference for Transfer endpoints and webhooks

Intelligently process transfers between accounts in the US.

Transfer endpoints are only supported in Plaid's Sandbox and Production environments.

Initiating Transfers
/transfer/authorization/createCreate a transfer authorization
/transfer/createCreate a transfer
/transfer/cancelCancel a transfer
Reading Transfers
/transfer/getRetrieve information about a transfer
/transfer/listRetrieve a list of transfers and their statuses
/transfer/event/listRetrieve a list of transfer events
/transfer/event/syncSync transfer events
/transfer/sweep/getRetrieve information about a sweep
/transfer/sweep/listRetrieve a list of sweeps
Account Linking
/payment_profile/createCreate a Payment Profile
/payment_profile/getRetrieve the status of a Payment Profile
/payment_profile/removeRemove a Payment Profile
/transfer/capabilities/getDetermine RTP eligibility for a Plaid Item
/transfer/intent/createCreate a transfer intent and invoke Transfer UI (Transfer UI only)
/transfer/intent/getRetrieve information about a transfer intent (Transfer UI only)
/transfer/migrate_accountCreate an Item to use with Transfer from known account and routing numbers
Recurring Transfers
/transfer/recurring/createCreate a recurring transfer
/transfer/recurring/cancelCancel a recurring transfer
/transfer/recurring/getRetrieve information about a recurring transfer
/transfer/recurring/listRetrieve a list of recurring transfers
Refunds
/transfer/refund/createCreate a refund for a transfer
/transfer/refund/cancelCancel a refund
/transfer/refund/getRetrieve information about a refund
Platform Payments
/transfer/originator/createCreate a new originator
/transfer/originator/getGet the status of an originator's onboarding
/transfer/originator/listGet the status of all originators' onboarding
/transfer/questionnaire/createGenerate a Plaid-hosted onboarding UI URL
/transfer/diligence/submitSubmit transfer diligence on behalf of the originator
/transfer/diligence/document/uploadUpload transfer diligence document on behalf of the originator
Program Metrics
/transfer/metrics/getGet transfer product usage metrics
/transfer/configuration/getGet transfer product configuration
Balances
/transfer/balance/getRetrieve information about a balance held with Plaid
Sandbox
/sandbox/payment_profile/reset_loginSimulate a Payment Profile login invalidation
/sandbox/transfer/simulateSimulate a transfer event (Sandbox only)
/sandbox/transfer/sweep/simulateSimulate creating a sweep (Sandbox only)
/sandbox/transfer/fire_webhookSimulate a transfer webhook (Sandbox only)
/sandbox/transfer/test_clock/createCreate a test clock (Sandbox only)
/sandbox/transfer/test_clock/advanceAdvance a test clock (Sandbox only)
/sandbox/transfer/test_clock/getRetrieve information about a test clock (Sandbox only)
/sandbox/transfer/test_clock/listRetrieve a list of test clocks (Sandbox only)
Webhooks
TRANSFER_EVENTS_UPDATENew transfer events available
RECURRING_CANCELLEDA recurring transfer has been cancelled by Plaid
RECURRING_NEW_TRANSFERA new transfer of a recurring transfer has been originated
RECURRING_TRANSFER_SKIPPEDAn instance of a scheduled recurring transfer could not be created

Endpoints

/transfer/authorization/create

Create a transfer authorization

Use the /transfer/authorization/create endpoint to determine transfer failure risk.
In Plaid's Sandbox environment the decisions will be returned as follows:
- To approve a transfer with null rationale code, make an authorization request with an amount less than the available balance in the account.
- To approve a transfer with the rationale code MANUALLY_VERIFIED_ITEM, create an Item in Link through the Same Day Micro-deposits flow.
- To approve a transfer with the rationale code ITEM_LOGIN_REQUIRED, reset the login for an Item.
- To decline a transfer with the rationale code NSF, the available balance on the account must be less than the authorization amount. See Create Sandbox test data for details on how to customize data in Sandbox.
- To decline a transfer with the rationale code RISK, the available balance on the account must be exactly $0. See Create Sandbox test data for details on how to customize data in Sandbox.
The fields device.ip_address and device.user_agent are required for all sessions where the end-user is present. For example, when a user is authorizing a one-time payment from their device.

transfer/authorization/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
string
The Plaid access_token for the account that will be debited or credited. Required if not using payment_profile_token.
account_id
string
The Plaid account_id corresponding to the end-user account that will be debited or credited. Required when creating a transfer using an access_token.
funding_account_id
string
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited. Defaults to the account configured during onboarding.
payment_profile_token
string
The payment profile token associated with the Payment Profile that will be debited or credited. Required if not using access_token.
type
requiredstring
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account.

Possible values: debit, credit
network
requiredstring
The network or rails used for the transfer.
For transfers submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded if applicable.

Possible values: ach, same-day-ach, rtp
amount
requiredstring
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
ach_class
string
Specifies the use case of the transfer. Required for transfers on an ACH network.
"ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts
"ppd" - Prearranged Payment or Deposit - the transfer is part of a pre-existing relationship with a consumer, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web
user
requiredobject
The legal name and other information for the account holder.
legal_name
requiredstring
The user's legal name.
phone_number
string
The user's phone number. In order to qualify for a guaranteed transfer, at least one of phone_number or email_address must be provided.
email_address
string
The user's email address. In order to qualify for a guaranteed transfer, at least one of phone_number or email_address must be provided.
address
object
The address associated with the account holder. Providing this data will improve the likelihood that Plaid will be able to guarantee the transfer, if applicable.
street
string
The street number and name (i.e., "100 Market St.").
city
string
Ex. "San Francisco"
region
string
The state or province (e.g., "CA").
postal_code
string
The postal code (e.g., "94103").
country
string
A two-letter country code (e.g., "US").
device
object
Information about the device being used to initiate the authorization.
ip_address
string
The IP address of the device being used to initiate the authorization. Required when the end-user is present at authorization create time.
user_agent
string
The user agent of the device being used to initiate the authorization. Required when the end-user is present at authorization create time.
iso_currency_code
string
The currency of the transfer amount. The default value is "USD".
idempotency_key
string
A random key provided by the client, per unique authorization, which expires after 48 hours. Maximum of 50 characters.
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create an authorization fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single authorization is created.
This idempotency key expires after 48 hours, after which the same key can be reused. Failure to provide this key may result in duplicate charges.
Required for guaranteed ACH customers.

Max length: 50
user_present
boolean
If the end user is initiating the specific transfer themselves via an interactive UI, this should be true; for automatic recurring payments where the end user is not actually initiating each individual transfer, it should be false.
beacon_session_id
string
The unique identifier returned by Plaid's beacon when it is run on your webpage.
originator_client_id
string
The Plaid client ID that is the originator of this transfer. Only needed if creating transfers on behalf of another client as a third-party sender (TPS).
credit_funds_source
string
Specifies the source of funds for the transfer. Only valid for credit transfers, and defaults to sweep if not specified. This field is not specified for debit transfers.
sweep - Sweep funds from your funding account prefunded_rtp_credits - Use your prefunded RTP credit balance with Plaid prefunded_ach_credits - Use your prefunded ACH credit balance with Plaid

Possible values: sweep, prefunded_rtp_credits, prefunded_ach_credits, null
test_clock_id
string
Plaid’s unique identifier for a test clock. This field may only be used when using sandbox environment. If provided, the authorization is created at the virtual_time on the provided test_clock.
Select Language
1const request: TransferAuthorizationCreateRequest = {
2  access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
3  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
4  type: 'credit',
5  network: 'ach',
6  amount: '12.34',
7  ach_class: 'ppd',
8  user: {
9    legal_name: 'Anne Charleston',
10  },
11};
12
13try {
14  const response = await client.transferAuthorizationCreate(request);
15  const authorizationId = response.data.authorization.id;
16} catch (error) {
17  // handle error
18}
transfer/authorization/create

Response fields and example

authorization
object
Contains the authorization decision for a proposed transfer.
id
string
Plaid’s unique identifier for a transfer authorization.
created
string
The datetime representing when the authorization was created, in the format 2006-01-02T15:04:05Z.

Format: date-time
decision
string
A decision regarding the proposed transfer.
approved – The proposed transfer has received the end user's consent and has been approved for processing by Plaid. The decision_rationale field is set if Plaid was unable to fetch the account information. You may proceed with the transfer, but further review is recommended (i.e., use Link in update to re-authenticate your user when decision_rationale.code is ITEM_LOGIN_REQUIRED). Refer to the code field in the decision_rationale object for details.
declined – Plaid reviewed the proposed transfer and declined processing. Refer to the code field in the decision_rationale object for details.

Possible values: approved, declined
decision_rationale
nullableobject
The rationale for Plaid's decision regarding a proposed transfer. It is always set for declined decisions, and may or may not be null for approved decisions.
code
string
A code representing the rationale for approving or declining the proposed transfer. Possible values are:
MANUALLY_VERIFIED_ITEM – Item created via same-day micro deposits, limited information available. Plaid will offer approved as a transaction decision.
ITEM_LOGIN_REQUIRED – Unable to collect the account information due to Item staleness. Can be rectified using Link in update mode. Plaid will offer approved as a transaction decision.
PAYMENT_PROFILE_LOGIN_REQUIRED - Unable to collect the account information due to invalid login when using Payment Profiles. Can be rectified using update mode for Payment Profile. Plaid will offer approved as a transaction decision.
ERROR – Unable to collect the account information due to an error. Plaid will offer approved as a transaction decision.
NSF – Transaction likely to result in a return due to insufficient funds. Plaid will offer declined as a transaction decision.
RISK - Transaction is high-risk. Plaid will offer declined as a transaction decision.
TRANSFER_LIMIT_REACHED - One or several transfer limits are reached, e.g. monthly transfer limit. Plaid will offer declined as a transaction decision.
MIGRATED_ACCOUNT_ITEM - Item created via /transfer/account_migration endpoint, limited information available. Plaid will offer approved as a transaction decision.

Possible values: NSF, RISK, TRANSFER_LIMIT_REACHED, MANUALLY_VERIFIED_ITEM, ITEM_LOGIN_REQUIRED, PAYMENT_PROFILE_LOGIN_REQUIRED, ERROR, MIGRATED_ACCOUNT_ITEM
description
string
A human-readable description of the code associated with a transfer approval or transfer decline.
signal_insights
nullableobject
Signal insights including scores and attributes. This response is offered as an add-on to /transfer/authorization/create. To request access to these fields please contact your Plaid account manager.
scores
object
Risk scoring details broken down by risk category.
customer_initiated_return_risk
object
The object contains a risk score and a risk tier that evaluate the transaction return risk of an unauthorized debit. Common return codes in this category include: "R05", "R07", "R10", "R11", "R29". These returns typically have a return time frame of up to 60 calendar days. During this period, the customer of financial institutions can dispute a transaction as unauthorized.
score
integer
A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood.

Minimum: 1
Maximum: 99
risk_tier
integer
A tier corresponding to the projected likelihood that the transaction, if initiated, will be subject to a return.
In the customer_initiated_return_risk object, there are five risk tiers corresponding to the scores: 1: Predicted customer-initiated return incidence rate between 0.00% - 0.02% 2: Predicted customer-initiated return incidence rate between 0.02% - 0.05% 3: Predicted customer-initiated return incidence rate between 0.05% - 0.1% 4: Predicted customer-initiated return incidence rate between 0.1% - 0.5% 5: Predicted customer-initiated return incidence rate greater than 0.5%

Minimum: 1
Maximum: 5
bank_initiated_return_risk
object
The object contains a risk score and a risk tier that evaluate the transaction return risk because an account is overdrawn or because an ineligible account is used. Common return codes in this category include: "R01", "R02", "R03", "R04", "R06", "R08", "R09", "R13", "R16", "R17", "R20", "R23". These returns have a turnaround time of 2 banking days.
score
integer
A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood.

Minimum: 1
Maximum: 99
risk_tier
integer
In the bank_initiated_return_risk object, there are eight risk tiers corresponding to the scores: 1: Predicted bank-initiated return incidence rate between 0.0% - 0.5% 2: Predicted bank-initiated return incidence rate between 0.5% - 1.5% 3: Predicted bank-initiated return incidence rate between 1.5% - 3% 4: Predicted bank-initiated return incidence rate between 3% - 5% 5: Predicted bank-initiated return incidence rate between 5% - 10% 6: Predicted bank-initiated return incidence rate between 10% - 15% 7: Predicted bank-initiated return incidence rate between 15% and 50% 8: Predicted bank-initiated return incidence rate greater than 50%

Minimum: 1
Maximum: 8
warnings
[object]
If bank information was not available to be used in the Signal model, this array contains warnings describing why bank data is missing. If you want to receive an API error instead of Signal scores in the case of missing bank data, file a support ticket or contact your Plaid account manager.
warning_type
string
A broad categorization of the warning. Safe for programmatic use.
warning_code
string
The warning code identifies a specific kind of warning that pertains to the error causing bank data to be missing. Safe for programmatic use. For more details on warning codes, please refer to Plaid standard error codes documentation. In case you receive the ITEM_LOGIN_REQUIRED warning, we recommend re-authenticating your user by implementing Link's update mode. This will guide your user to fix their credentials, allowing Plaid to start fetching data again for future Signal requests.
warning_message
string
A developer-friendly representation of the warning type. This may change over time and is not safe for programmatic use.
proposed_transfer
object
Details regarding the proposed transfer.
ach_class
string
Specifies the use case of the transfer. Required for transfers on an ACH network.
"ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts
"ppd" - Prearranged Payment or Deposit - the transfer is part of a pre-existing relationship with a consumer, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web
account_id
string
The Plaid account_id for the account that will be debited or credited.
funding_account_id
nullablestring
The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.
type
string
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account.

Possible values: debit, credit
user
object
The legal name and other information for the account holder.
legal_name
string
The user's legal name.
phone_number
nullablestring
The user's phone number.
email_address
nullablestring
The user's email address.
address
nullableobject
The address associated with the account holder.
street
nullablestring
The street number and name (i.e., "100 Market St.").
city
nullablestring
Ex. "San Francisco"
region
nullablestring
The state or province (e.g., "CA").
postal_code
nullablestring
The postal code (e.g., "94103").
country
nullablestring
A two-letter country code (e.g., "US").
amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
network
string
The network or rails used for the transfer.
iso_currency_code
string
The currency of the transfer amount. The default value is "USD".
originator_client_id
nullablestring
The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a third-party sender (TPS).
credit_funds_source
nullablestring
Specifies the source of funds for the transfer. Only valid for credit transfers, and defaults to sweep if not specified. This field is not specified for debit transfers.
sweep - Sweep funds from your funding account prefunded_rtp_credits - Use your prefunded RTP credit balance with Plaid prefunded_ach_credits - Use your prefunded ACH credit balance with Plaid

Possible values: sweep, prefunded_rtp_credits, prefunded_ach_credits, null
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "authorization": {
3    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
4    "created": "2020-08-06T17:27:15Z",
5    "decision": "approved",
6    "decision_rationale": null,
7    "guarantee_decision": "GUARANTEED",
8    "guarantee_decision_rationale": null,
9    "proposed_transfer": {
10      "ach_class": "ppd",
11      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
12      "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
13      "type": "credit",
14      "user": {
15        "legal_name": "Anne Charleston",
16        "phone_number": "510-555-0128",
17        "email_address": "acharleston@email.com",
18        "address": {
19          "street": "123 Main St.",
20          "city": "San Francisco",
21          "region": "CA",
22          "postal_code": "94053",
23          "country": "US"
24        }
25      },
26      "amount": "12.34",
27      "network": "ach",
28      "iso_currency_code": "USD",
29      "origination_account_id": "",
30      "originator_client_id": null,
31      "credit_funds_source": "sweep"
32    }
33  },
34  "request_id": "saKrIBuEB9qJZno"
35}
Was this helpful?

/transfer/balance/get

Retrieve a balance held with Plaid

Use the /transfer/balance/get endpoint to view a balance held with Plaid.

transfer/balance/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
originator_client_id
string
Client ID of the end customer.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
type
string
The type of balance.
prefunded_rtp_credits - Your prefunded RTP credit balance with Plaid prefunded_ach_credits - Your prefunded ACH credit balance with Plaid

Possible values: prefunded_rtp_credits, prefunded_ach_credits
Select Language
1const request: TransferBalanceGetRequest = {
2  type: 'prefunded_rtp_credits',
3};
4
5try {
6  const response = await client.transferBalanceGet(request);
7  const available_balance = response.data.balance.available;
8} catch (error) {
9  // handle error
10}
transfer/balance/get

Response fields and example

balance
object
Information about the balance held with Plaid.
available
string
The amount of this balance available for use (decimal string with two digits of precision e.g. "10.00").
current
string
The available balance, plus amount of pending funds that in processing (decimal string with two digits of precision e.g. "10.00").
type
string
The type of balance.
prefunded_rtp_credits - Your prefunded RTP credit balance with Plaid prefunded_ach_credits - Your prefunded ACH credit balance with Plaid

Possible values: prefunded_rtp_credits, prefunded_ach_credits
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "balance": {
3    "available": "1721.70",
4    "type": "prefunded_rtp_credits"
5  },
6  "request_id": "saKrIBuEB9qJZno"
7}
Was this helpful?

/transfer/capabilities/get

Get RTP eligibility information of a transfer

Use the /transfer/capabilities/get endpoint to determine the RTP eligibility information of a transfer.

transfer/capabilities/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
string
The Plaid access_token for the account that will be debited or credited. Required if not using payment_profile_token.
account_id
string
The Plaid account_id corresponding to the end-user account that will be debited or credited. Required when creating a transfer using an access_token.
payment_profile_token
string
A payment profile token associated with the Payment Profile data that is being requested.
Select Language
1const request: TransferCapabilitiesGetRequest = {
2  access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
3  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
4};
5
6try {
7  const response = await client.transferAuthorizationCreate(request);
8  const authorizationId = response.data.authorization.id;
9} catch (error) {
10  // handle error
11}
transfer/capabilities/get

Response fields and example

institution_supported_networks
object
Contains the RTP network and types supported by the linked Item's institution.
rtp
object
Contains the supported service types in RTP
credit
boolean
When true, the linked Item's institution supports RTP credit transfer.

Default: false
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "institution_supported_networks": {
3    "rtp": {
4      "credit": true
5    }
6  },
7  "request_id": "saKrIBuEB9qJZno"
8}
Was this helpful?

/transfer/configuration/get

Get transfer product configuration

Use the /transfer/configuration/get endpoint to view your transfer product configurations.

transfer/configuration/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
originator_client_id
string
The Plaid client ID of the transfer originator. Should only be present if client_id is a third-party sender (TPS).
Select Language
1const request: TransferConfigurationGetRequest = {
2  originator_client_id: '61b8f48ded273e001aa8db6d',
3};
4
5try {
6  const response = await client.transferConfigurationGet(request);
7} catch (error) {
8  // handle error
9}
transfer/configuration/get

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
max_single_transfer_amount
string
The max limit of dollar amount of a single transfer (decimal string with two digits of precision e.g. "10.00").
max_single_transfer_credit_amount
string
The max limit of dollar amount of a single credit transfer (decimal string with two digits of precision e.g. "10.00").
max_single_transfer_debit_amount
string
The max limit of dollar amount of a single debit transfer (decimal string with two digits of precision e.g. "10.00").
max_daily_credit_amount
string
The max limit of sum of dollar amount of credit transfers in last 24 hours (decimal string with two digits of precision e.g. "10.00").
max_daily_debit_amount
string
The max limit of sum of dollar amount of debit transfers in last 24 hours (decimal string with two digits of precision e.g. "10.00").
max_monthly_amount
string
The max limit of sum of dollar amount of credit and debit transfers in one calendar month (decimal string with two digits of precision e.g. "10.00").
max_monthly_credit_amount
string
The max limit of sum of dollar amount of credit transfers in one calendar month (decimal string with two digits of precision e.g. "10.00").
max_monthly_debit_amount
string
The max limit of sum of dollar amount of debit transfers in one calendar month (decimal string with two digits of precision e.g. "10.00").
iso_currency_code
string
The currency of the dollar amount, e.g. "USD".
1{
2  "max_single_transfer_amount": "1000.00",
3  "max_single_transfer_credit_amount": "1000.00",
4  "max_single_transfer_debit_amount": "1000.00",
5  "max_daily_credit_amount": "50000.00",
6  "max_daily_debit_amount": "50000.00",
7  "max_monthly_amount": "500000.00",
8  "max_monthly_credit_amount": "500000.00",
9  "max_monthly_debit_amount": "500000.00",
10  "iso_currency_code": "USD",
11  "request_id": "saKrIBuEB9qJZno"
12}
Was this helpful?

/transfer/create

Create a transfer

Use the /transfer/create endpoint to initiate a new transfer.

transfer/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
string
The Plaid access_token for the account that will be debited or credited. Required if not using payment_profile_token.
account_id
string
The Plaid account_id corresponding to the end-user account that will be debited or credited. Required when creating a transfer using an access_token.
payment_profile_token
string
The payment profile token associated with the Payment Profile that will be debited or credited. Required if not using access_token.
authorization_id
requiredstring
Plaid’s unique identifier for a transfer authorization. This parameter also serves the purpose of acting as an idempotency identifier.
amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
description
requiredstring
The transfer description. Maximum of 15 characters. If reprocessing a returned transfer, please note that the description field must be "Retry" to indicate that it's a retry of a previously returned transfer. You may retry a transfer up to 2 times, within 180 days of creating the original transfer. Only transfers that were returned with code R01 or R09 may be retried. For a full listing of ACH return codes, see Transfer errors.

Max length: 15
metadata
object
The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters
test_clock_id
string
Plaid’s unique identifier for a test clock. This field may only be used when using sandbox environment. If provided, the transfer is created at the virtual_time on the provided test_clock.
Select Language
1const request: TransferCreateRequest = {
2  amount: '12.34',
3  description: 'payment',
4  access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
5  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
6  authorization_id: '231h012308h3101z21909sw',
7};
8try {
9  const response = await client.transferCreate(request);
10  const transfer = response.data.transfer;
11} catch (error) {
12  // handle error
13}
transfer/create

Response fields and example

transfer
object
Represents a transfer within the Transfers API.
id
string
Plaid’s unique identifier for a transfer.
authorization_id
string
Plaid’s unique identifier for a transfer authorization.
ach_class
string
Specifies the use case of the transfer. Required for transfers on an ACH network.
"ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts
"ppd" - Prearranged Payment or Deposit - the transfer is part of a pre-existing relationship with a consumer, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web
account_id
string
The Plaid account_id corresponding to the end-user account that will be debited or credited.
funding_account_id
nullablestring
The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.
type
string
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account.

Possible values: debit, credit
user
object
The legal name and other information for the account holder.
legal_name
string
The user's legal name.
phone_number
nullablestring
The user's phone number.
email_address
nullablestring
The user's email address.
address
nullableobject
The address associated with the account holder.
street
nullablestring
The street number and name (i.e., "100 Market St.").
city
nullablestring
Ex. "San Francisco"
region
nullablestring
The state or province (e.g., "CA").
postal_code
nullablestring
The postal code (e.g., "94103").
country
nullablestring
A two-letter country code (e.g., "US").
amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
description
string
The description of the transfer.
created
string
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
status
string
The status of the transfer.
pending: A new transfer was created; it is in the pending state. posted: The transfer has been successfully submitted to the payment network. settled: Credits are available to be withdrawn or debits have been deducted from the Plaid linked account. cancelled: The transfer was cancelled by the client. failed: The transfer failed, no funds were moved. returned: A posted transfer was returned.

Possible values: pending, posted, settled, cancelled, failed, returned
sweep_status
nullablestring
The status of the sweep for the transfer.
unswept: The transfer hasn't been swept yet. swept: The transfer was swept to the sweep account. swept_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. return_swept: The transfer was returned, funds were pulled back or pushed back to the sweep account. null: The transfer will never be swept (e.g. if the transfer is cancelled or returned before being swept)

Possible values: null, unswept, swept, swept_settled, return_swept
network
string
The network or rails used for the transfer.
For transfers submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded if applicable.

Possible values: ach, same-day-ach, rtp
cancellable
boolean
When true, you can still cancel this transfer.
failure_reason
nullableobject
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.
ach_return_code
nullablestring
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.
description
string
A human-readable description of the reason for the failure or reversal.
metadata
nullableobject
The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
standard_return_window
nullablestring
The date 3 business days from settlement date indicating the following ACH returns can no longer happen: R01, R02, R03, R29. This will be of the form YYYY-MM-DD.

Format: date
unauthorized_return_window
nullablestring
The date 61 business days from settlement date indicating the following ACH returns can no longer happen: R05, R07, R10, R11, R51, R33, R37, R38, R51, R52, R53. This will be of the form YYYY-MM-DD.

Format: date
expected_settlement_date
nullablestring
The expected date when the full amount of the transfer settles at the consumers’ account, if the transfer is credit; or at the customer's business checking account, if the transfer is debit. Only set for ACH transfers and is null for non-ACH transfers. Only set for ACH transfers. This will be of the form YYYY-MM-DD.

Format: date
originator_client_id
nullablestring
The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a third-party sender (TPS).
refunds
[object]
A list of refunds associated with this transfer.
id
string
Plaid’s unique identifier for a refund.
transfer_id
string
The ID of the transfer to refund.
amount
string
The amount of the refund (decimal string with two digits of precision e.g. "10.00").
status
string
The status of the refund.
pending: A new refund was created; it is in the pending state. posted: The refund has been successfully submitted to the payment network. settled: Credits have been refunded to the Plaid linked account. cancelled: The refund was cancelled by the client. failed: The refund has failed. returned: The refund was returned.

Possible values: pending, posted, cancelled, failed, settled, returned
failure_reason
nullableobject
The failure reason if the event type for a refund is "failed" or "returned". Null value otherwise.
ach_return_code
nullablestring
The ACH return code, e.g. R01. A return code will be provided if and only if the refund status is returned. For a full listing of ACH return codes, see Transfer errors.
description
string
A human-readable description of the reason for the failure or reversal.
created
string
The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
recurring_transfer_id
nullablestring
The id of the recurring transfer if this transfer belongs to a recurring transfer.
expected_sweep_settlement_schedule
[object]
The expected sweep settlement schedule of this transfer, assuming this transfer is not returned. Only applies to ACH debit transfers.
sweep_settlement_date
string
The settlement date of a sweep for this transfer.

Format: date
swept_settled_amount
string
The accumulated amount that has been swept by sweep_settlement_date.
credit_funds_source
nullablestring
Specifies the source of funds for the transfer. Only valid for credit transfers, and defaults to sweep if not specified. This field is not specified for debit transfers.
sweep - Sweep funds from your funding account prefunded_rtp_credits - Use your prefunded RTP credit balance with Plaid prefunded_ach_credits - Use your prefunded ACH credit balance with Plaid

Possible values: sweep, prefunded_rtp_credits, prefunded_ach_credits, null
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transfer": {
3    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
4    "authorization_id": "c9f90aa1-2949-c799-e2b6-ea05c89bb586",
5    "ach_class": "ppd",
6    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
7    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
8    "type": "credit",
9    "user": {
10      "legal_name": "Anne Charleston",
11      "phone_number": "510-555-0128",
12      "email_address": "acharleston@email.com",
13      "address": {
14        "street": "123 Main St.",
15        "city": "San Francisco",
16        "region": "CA",
17        "postal_code": "94053",
18        "country": "US"
19      }
20    },
21    "amount": "12.34",
22    "description": "payment",
23    "created": "2020-08-06T17:27:15Z",
24    "refunds": [],
25    "status": "pending",
26    "network": "ach",
27    "cancellable": true,
28    "guarantee_decision": "GUARANTEED",
29    "guarantee_decision_rationale": null,
30    "failure_reason": null,
31    "metadata": {
32      "key1": "value1",
33      "key2": "value2"
34    },
35    "origination_account_id": "",
36    "iso_currency_code": "USD",
37    "standard_return_window": "2020-08-07",
38    "unauthorized_return_window": "2020-10-07",
39    "expected_settlement_date": "2020-08-04",
40    "originator_client_id": "569ed2f36b3a3a021713abc1",
41    "recurring_transfer_id": null,
42    "credit_funds_source": "sweep"
43  },
44  "request_id": "saKrIBuEB9qJZno"
45}
Was this helpful?

/transfer/cancel

Cancel a transfer

Use the /transfer/cancel endpoint to cancel a transfer. A transfer is eligible for cancellation if the cancellable property returned by /transfer/get is true.

transfer/cancel

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
transfer_id
requiredstring
Plaid’s unique identifier for a transfer.
originator_client_id
string
The Plaid client ID of the transfer originator. Should only be present if client_id is a third-party sender (TPS).
Select Language
1const request: TransferCancelRequest = {
2  transfer_id: '123004561178933',
3};
4try {
5  const response = await plaidClient.transferCancel(request);
6  const request_id = response.data.request_id;
7} catch (error) {
8  // handle error
9}
transfer/cancel

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "saKrIBuEB9qJZno"
3}
Was this helpful?

/transfer/get

Retrieve a transfer

The /transfer/get endpoint fetches information about the transfer corresponding to the given transfer_id.

transfer/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
transfer_id
requiredstring
Plaid’s unique identifier for a transfer.
originator_client_id
string
The Plaid client ID of the transfer originator. Should only be present if client_id is a third-party sender (TPS).
Select Language
1const request: TransferGetRequest = {
2  transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
3};
4try {
5  const response = await plaidClient.transferGet(request);
6  const transfer = response.data.transfer;
7} catch (error) {
8  // handle error
9}
transfer/get

Response fields and example

transfer
object
Represents a transfer within the Transfers API.
id
string
Plaid’s unique identifier for a transfer.
authorization_id
string
Plaid’s unique identifier for a transfer authorization.
ach_class
string
Specifies the use case of the transfer. Required for transfers on an ACH network.
"ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts
"ppd" - Prearranged Payment or Deposit - the transfer is part of a pre-existing relationship with a consumer, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web
account_id
string
The Plaid account_id corresponding to the end-user account that will be debited or credited.
funding_account_id
nullablestring
The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.
type
string
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account.

Possible values: debit, credit
user
object
The legal name and other information for the account holder.
legal_name
string
The user's legal name.
phone_number
nullablestring
The user's phone number.
email_address
nullablestring
The user's email address.
address
nullableobject
The address associated with the account holder.
street
nullablestring
The street number and name (i.e., "100 Market St.").
city
nullablestring
Ex. "San Francisco"
region
nullablestring
The state or province (e.g., "CA").
postal_code
nullablestring
The postal code (e.g., "94103").
country
nullablestring
A two-letter country code (e.g., "US").
amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
description
string
The description of the transfer.
created
string
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
status
string
The status of the transfer.
pending: A new transfer was created; it is in the pending state. posted: The transfer has been successfully submitted to the payment network. settled: Credits are available to be withdrawn or debits have been deducted from the Plaid linked account. cancelled: The transfer was cancelled by the client. failed: The transfer failed, no funds were moved. returned: A posted transfer was returned.

Possible values: pending, posted, settled, cancelled, failed, returned
sweep_status
nullablestring
The status of the sweep for the transfer.
unswept: The transfer hasn't been swept yet. swept: The transfer was swept to the sweep account. swept_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. return_swept: The transfer was returned, funds were pulled back or pushed back to the sweep account. null: The transfer will never be swept (e.g. if the transfer is cancelled or returned before being swept)

Possible values: null, unswept, swept, swept_settled, return_swept
network
string
The network or rails used for the transfer.
For transfers submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded if applicable.

Possible values: ach, same-day-ach, rtp
cancellable
boolean
When true, you can still cancel this transfer.
failure_reason
nullableobject
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.
ach_return_code
nullablestring
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.
description
string
A human-readable description of the reason for the failure or reversal.
metadata
nullableobject
The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
standard_return_window
nullablestring
The date 3 business days from settlement date indicating the following ACH returns can no longer happen: R01, R02, R03, R29. This will be of the form YYYY-MM-DD.

Format: date
unauthorized_return_window
nullablestring
The date 61 business days from settlement date indicating the following ACH returns can no longer happen: R05, R07, R10, R11, R51, R33, R37, R38, R51, R52, R53. This will be of the form YYYY-MM-DD.

Format: date
expected_settlement_date
nullablestring
The expected date when the full amount of the transfer settles at the consumers’ account, if the transfer is credit; or at the customer's business checking account, if the transfer is debit. Only set for ACH transfers and is null for non-ACH transfers. Only set for ACH transfers. This will be of the form YYYY-MM-DD.

Format: date
originator_client_id
nullablestring
The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a third-party sender (TPS).
refunds
[object]
A list of refunds associated with this transfer.
id
string
Plaid’s unique identifier for a refund.
transfer_id
string
The ID of the transfer to refund.
amount
string
The amount of the refund (decimal string with two digits of precision e.g. "10.00").
status
string
The status of the refund.
pending: A new refund was created; it is in the pending state. posted: The refund has been successfully submitted to the payment network. settled: Credits have been refunded to the Plaid linked account. cancelled: The refund was cancelled by the client. failed: The refund has failed. returned: The refund was returned.

Possible values: pending, posted, cancelled, failed, settled, returned
failure_reason
nullableobject
The failure reason if the event type for a refund is "failed" or "returned". Null value otherwise.
ach_return_code
nullablestring
The ACH return code, e.g. R01. A return code will be provided if and only if the refund status is returned. For a full listing of ACH return codes, see Transfer errors.
description
string
A human-readable description of the reason for the failure or reversal.
created
string
The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
recurring_transfer_id
nullablestring
The id of the recurring transfer if this transfer belongs to a recurring transfer.
expected_sweep_settlement_schedule
[object]
The expected sweep settlement schedule of this transfer, assuming this transfer is not returned. Only applies to ACH debit transfers.
sweep_settlement_date
string
The settlement date of a sweep for this transfer.

Format: date
swept_settled_amount
string
The accumulated amount that has been swept by sweep_settlement_date.
credit_funds_source
nullablestring
Specifies the source of funds for the transfer. Only valid for credit transfers, and defaults to sweep if not specified. This field is not specified for debit transfers.
sweep - Sweep funds from your funding account prefunded_rtp_credits - Use your prefunded RTP credit balance with Plaid prefunded_ach_credits - Use your prefunded ACH credit balance with Plaid

Possible values: sweep, prefunded_rtp_credits, prefunded_ach_credits, null
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transfer": {
3    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
4    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
5    "ach_class": "ppd",
6    "amount": "12.34",
7    "cancellable": true,
8    "created": "2020-08-06T17:27:15Z",
9    "description": "Desc",
10    "guarantee_decision": null,
11    "guarantee_decision_rationale": null,
12    "failure_reason": {
13      "ach_return_code": "R13",
14      "description": "Invalid ACH routing number"
15    },
16    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
17    "authorization_id": "c9f90aa1-2949-c799-e2b6-ea05c89bb586",
18    "metadata": {
19      "key1": "value1",
20      "key2": "value2"
21    },
22    "network": "ach",
23    "origination_account_id": "",
24    "originator_client_id": null,
25    "refunds": [],
26    "status": "pending",
27    "type": "credit",
28    "iso_currency_code": "USD",
29    "standard_return_window": "2020-08-07",
30    "unauthorized_return_window": "2020-10-07",
31    "expected_settlement_date": "2020-08-04",
32    "user": {
33      "email_address": "acharleston@email.com",
34      "legal_name": "Anne Charleston",
35      "phone_number": "510-555-0128",
36      "address": {
37        "street": "123 Main St.",
38        "city": "San Francisco",
39        "region": "CA",
40        "postal_code": "94053",
41        "country": "US"
42      }
43    },
44    "recurring_transfer_id": null,
45    "credit_funds_source": "sweep"
46  },
47  "request_id": "saKrIBuEB9qJZno"
48}
Was this helpful?

/transfer/list

List transfers

Use the /transfer/list endpoint to see a list of all your transfers and their statuses. Results are paginated; use the count and offset query parameters to retrieve the desired transfers.

transfer/list

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
start_date
string
The start datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time
end_date
string
The end datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time
count
integer
The maximum number of transfers to return.

Minimum: 1
Maximum: 25
Default: 25
offset
integer
The number of transfers to skip before returning results.

Default: 0
Minimum: 0
originator_client_id
string
Filter transfers to only those with the specified originator client.
funding_account_id
string
Filter transfers to only those with the specified funding_account_id.
Select Language
1const request: TransferListRequest = {
2  start_date: '2019-12-06T22:35:49Z',
3  end_date: '2019-12-12T22:35:49Z',
4  count: 14,
5  offset: 2,
6  origination_account_id: '8945fedc-e703-463d-86b1-dc0607b55460',
7};
8try {
9  const response = await plaidClient.transferList(request);
10  const transfers = response.data.transfers;
11  for (const transfer of transfers) {
12    // iterate through transfers
13  }
14} catch (error) {
15  // handle error
16}
transfer/list

Response fields and example

transfers
[object]
id
string
Plaid’s unique identifier for a transfer.
authorization_id
string
Plaid’s unique identifier for a transfer authorization.
ach_class
string
Specifies the use case of the transfer. Required for transfers on an ACH network.
"ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts
"ppd" - Prearranged Payment or Deposit - the transfer is part of a pre-existing relationship with a consumer, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web
account_id
string
The Plaid account_id corresponding to the end-user account that will be debited or credited.
funding_account_id
nullablestring
The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.
type
string
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account.

Possible values: debit, credit
user
object
The legal name and other information for the account holder.
legal_name
string
The user's legal name.
phone_number
nullablestring
The user's phone number.
email_address
nullablestring
The user's email address.
address
nullableobject
The address associated with the account holder.
street
nullablestring
The street number and name (i.e., "100 Market St.").
city
nullablestring
Ex. "San Francisco"
region
nullablestring
The state or province (e.g., "CA").
postal_code
nullablestring
The postal code (e.g., "94103").
country
nullablestring
A two-letter country code (e.g., "US").
amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
description
string
The description of the transfer.
created
string
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
status
string
The status of the transfer.
pending: A new transfer was created; it is in the pending state. posted: The transfer has been successfully submitted to the payment network. settled: Credits are available to be withdrawn or debits have been deducted from the Plaid linked account. cancelled: The transfer was cancelled by the client. failed: The transfer failed, no funds were moved. returned: A posted transfer was returned.

Possible values: pending, posted, settled, cancelled, failed, returned
sweep_status
nullablestring
The status of the sweep for the transfer.
unswept: The transfer hasn't been swept yet. swept: The transfer was swept to the sweep account. swept_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. return_swept: The transfer was returned, funds were pulled back or pushed back to the sweep account. null: The transfer will never be swept (e.g. if the transfer is cancelled or returned before being swept)

Possible values: null, unswept, swept, swept_settled, return_swept
network
string
The network or rails used for the transfer.
For transfers submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded if applicable.

Possible values: ach, same-day-ach, rtp
cancellable
boolean
When true, you can still cancel this transfer.
failure_reason
nullableobject
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.
ach_return_code
nullablestring
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.
description
string
A human-readable description of the reason for the failure or reversal.
metadata
nullableobject
The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
standard_return_window
nullablestring
The date 3 business days from settlement date indicating the following ACH returns can no longer happen: R01, R02, R03, R29. This will be of the form YYYY-MM-DD.

Format: date
unauthorized_return_window
nullablestring
The date 61 business days from settlement date indicating the following ACH returns can no longer happen: R05, R07, R10, R11, R51, R33, R37, R38, R51, R52, R53. This will be of the form YYYY-MM-DD.

Format: date
expected_settlement_date
nullablestring
The expected date when the full amount of the transfer settles at the consumers’ account, if the transfer is credit; or at the customer's business checking account, if the transfer is debit. Only set for ACH transfers and is null for non-ACH transfers. Only set for ACH transfers. This will be of the form YYYY-MM-DD.

Format: date
originator_client_id
nullablestring
The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a third-party sender (TPS).
refunds
[object]
A list of refunds associated with this transfer.
id
string
Plaid’s unique identifier for a refund.
transfer_id
string
The ID of the transfer to refund.
amount
string
The amount of the refund (decimal string with two digits of precision e.g. "10.00").
status
string
The status of the refund.
pending: A new refund was created; it is in the pending state. posted: The refund has been successfully submitted to the payment network. settled: Credits have been refunded to the Plaid linked account. cancelled: The refund was cancelled by the client. failed: The refund has failed. returned: The refund was returned.

Possible values: pending, posted, cancelled, failed, settled, returned
failure_reason
nullableobject
The failure reason if the event type for a refund is "failed" or "returned". Null value otherwise.
ach_return_code
nullablestring
The ACH return code, e.g. R01. A return code will be provided if and only if the refund status is returned. For a full listing of ACH return codes, see Transfer errors.
description
string
A human-readable description of the reason for the failure or reversal.
created
string
The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
recurring_transfer_id
nullablestring
The id of the recurring transfer if this transfer belongs to a recurring transfer.
expected_sweep_settlement_schedule
[object]
The expected sweep settlement schedule of this transfer, assuming this transfer is not returned. Only applies to ACH debit transfers.
sweep_settlement_date
string
The settlement date of a sweep for this transfer.

Format: date
swept_settled_amount
string
The accumulated amount that has been swept by sweep_settlement_date.
credit_funds_source
nullablestring
Specifies the source of funds for the transfer. Only valid for credit transfers, and defaults to sweep if not specified. This field is not specified for debit transfers.
sweep - Sweep funds from your funding account prefunded_rtp_credits - Use your prefunded RTP credit balance with Plaid prefunded_ach_credits - Use your prefunded ACH credit balance with Plaid

Possible values: sweep, prefunded_rtp_credits, prefunded_ach_credits, null
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transfers": [
3    {
4      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
5      "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
6      "ach_class": "ppd",
7      "amount": "12.34",
8      "cancellable": true,
9      "created": "2019-12-09T17:27:15Z",
10      "description": "Desc",
11      "guarantee_decision": null,
12      "guarantee_decision_rationale": null,
13      "failure_reason": {
14        "ach_return_code": "R13",
15        "description": "Invalid ACH routing number"
16      },
17      "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
18      "authorization_id": "c9f90aa1-2949-c799-e2b6-ea05c89bb586",
19      "metadata": {
20        "key1": "value1",
21        "key2": "value2"
22      },
23      "network": "ach",
24      "origination_account_id": "",
25      "originator_client_id": null,
26      "refunds": [],
27      "status": "pending",
28      "type": "credit",
29      "iso_currency_code": "USD",
30      "standard_return_window": "2020-08-07",
31      "unauthorized_return_window": "2020-10-07",
32      "expected_settlement_date": "2020-08-04",
33      "user": {
34        "email_address": "acharleston@email.com",
35        "legal_name": "Anne Charleston",
36        "phone_number": "510-555-0128",
37        "address": {
38          "street": "123 Main St.",
39          "city": "San Francisco",
40          "region": "CA",
41          "postal_code": "94053",
42          "country": "US"
43        }
44      },
45      "recurring_transfer_id": null,
46      "credit_funds_source": "sweep"
47    }
48  ],
49  "request_id": "saKrIBuEB9qJZno"
50}
Was this helpful?

/transfer/event/list

List transfer events

Use the /transfer/event/list endpoint to get a list of transfer events based on specified filter criteria.

transfer/event/list

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
start_date
string
The start datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time
end_date
string
The end datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time
transfer_id
string
Plaid’s unique identifier for a transfer.
account_id
string
The account ID to get events for all transactions to/from an account.
transfer_type
string
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into your origination account; a credit indicates a transfer of money out of your origination account.

Possible values: debit, credit, null
event_types
[string]
Filter events by event type.

Possible values: pending, cancelled, failed, posted, settled, returned, swept, swept_settled, return_swept
sweep_id
string
Plaid’s unique identifier for a sweep.
count
integer
The maximum number of transfer events to return. If the number of events matching the above parameters is greater than count, the most recent events will be returned.

Default: 25
Maximum: 25
Minimum: 1
offset
integer
The offset into the list of transfer events. When count=25 and offset=0, the first 25 events will be returned. When count=25 and offset=25, the next 25 events will be returned.

Default: 0
Minimum: 0
originator_client_id
string
Filter transfer events to only those with the specified originator client.
funding_account_id
string
Filter transfer events to only those with the specified funding_account_id.
Select Language
1const request: TransferEventListRequest = {
2  start_date: '2019-12-06T22:35:49Z',
3  end_date: '2019-12-12T22:35:49Z',
4  transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
5  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
6  transfer_type: 'credit',
7  event_types: ['pending', 'posted'],
8  count: 14,
9  offset: 2,
10  origination_account_id: '8945fedc-e703-463d-86b1-dc0607b55460',
11};
12try {
13  const response = await plaidClient.transferEventList(request);
14  const events = response.data.transfer_events;
15  for (const event of events) {
16    // iterate through events
17  }
18} catch (error) {
19  // handle error
20}
transfer/event/list

Response fields and example

transfer_events
[object]
event_id
integer
Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers.

Minimum: 0
timestamp
string
The datetime when this event occurred. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time
event_type
string
The type of event that this transfer represents.
pending: A new transfer was created; it is in the pending state.
cancelled: The transfer was cancelled by the client.
failed: The transfer failed, no funds were moved.
posted: The transfer has been successfully submitted to the payment network.
settled: Credits are available to be withdrawn or debits have been deducted from the Plaid linked account.
returned: A posted transfer was returned.
swept: The transfer was swept to / from the sweep account.
swept_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account.
return_swept: Due to the transfer being returned, funds were pulled from or pushed back to the sweep account.

Possible values: pending, cancelled, failed, posted, settled, returned, swept, swept_settled, return_swept
account_id
string
The account ID associated with the transfer.
funding_account_id
nullablestring
The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.
transfer_id
string
Plaid’s unique identifier for a transfer.
transfer_type
string
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account.

Possible values: debit, credit
transfer_amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
failure_reason
nullableobject
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.
ach_return_code
nullablestring
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.
description
string
A human-readable description of the reason for the failure or reversal.
sweep_id
nullablestring
Plaid’s unique identifier for a sweep.
sweep_amount
nullablestring
A signed amount of how much was swept or return_swept for this transfer (decimal string with two digits of precision e.g. "-5.50").
refund_id
nullablestring
Plaid’s unique identifier for a refund. A non-null value indicates the event is for the associated refund of the transfer.
originator_client_id
nullablestring
The Plaid client ID that is the originator of the transfer that this event applies to. Only present if the transfer was created on behalf of another client as a third-party sender (TPS).
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transfer_events": [
3    {
4      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
5      "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
6      "transfer_amount": "12.34",
7      "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
8      "transfer_type": "credit",
9      "event_id": 1,
10      "event_type": "posted",
11      "failure_reason": null,
12      "origination_account_id": "",
13      "originator_client_id": "569ed2f36b3a3a021713abc1",
14      "refund_id": null,
15      "sweep_amount": null,
16      "sweep_id": null,
17      "timestamp": "2019-12-09T17:27:15Z"
18    }
19  ],
20  "request_id": "mdqfuVxeoza6mhu"
21}
Was this helpful?

/transfer/metrics/get

Get transfer product usage metrics

Use the /transfer/metrics/get endpoint to view your transfer product usage metrics.

transfer/metrics/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
originator_client_id
string
The Plaid client ID of the transfer originator. Should only be present if client_id is a third-party sender (TPS).
Select Language
1const request: TransferMetricsGetRequest = {
2  originator_client_id: '61b8f48ded273e001aa8db6d',
3};
4
5try {
6  const response = await client.transferMetricsGet(request);
7} catch (error) {
8  // handle error
9}
transfer/metrics/get

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
daily_debit_transfer_volume
string
Sum of dollar amount of debit transfers in last 24 hours (decimal string with two digits of precision e.g. "10.00").
daily_credit_transfer_volume
string
Sum of dollar amount of credit transfers in last 24 hours (decimal string with two digits of precision e.g. "10.00").
monthly_transfer_volume
string
Sum of dollar amount of credit and debit transfers in current calendar month (decimal string with two digits of precision e.g. "10.00").
monthly_debit_transfer_volume
string
Sum of dollar amount of debit transfers in current calendar month (decimal string with two digits of precision e.g. "10.00").
monthly_credit_transfer_volume
string
Sum of dollar amount of credit transfers in current calendar month (decimal string with two digits of precision e.g. "10.00").
iso_currency_code
string
The currency of the dollar amount, e.g. "USD".
1{
2  "daily_debit_transfer_volume": "1234.56",
3  "daily_credit_transfer_volume": "567.89",
4  "monthly_transfer_volume": "12345.67",
5  "monthly_debit_transfer_volume": "10000.00",
6  "monthly_credit_transfer_volume": "2345.67",
7  "iso_currency_code": "USD",
8  "request_id": "saKrIBuEB9qJZno"
9}
Was this helpful?

/transfer/event/sync

Sync transfer events

/transfer/event/sync allows you to request up to the next 25 transfer events that happened after a specific event_id. Use the /transfer/event/sync endpoint to guarantee you have seen all transfer events.

transfer/event/sync

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
after_id
requiredinteger
The latest (largest) event_id fetched via the sync endpoint, or 0 initially.

Minimum: 0
count
integer
The maximum number of transfer events to return.

Default: 25
Minimum: 1
Maximum: 25
Select Language
1const request: TransferEventListRequest = {
2  after_id: 4,
3  count: 22,
4};
5try {
6  const response = await plaidClient.transferEventSync(request);
7  const events = response.data.transfer_events;
8  for (const event of events) {
9    // iterate through events
10  }
11} catch (error) {
12  // handle error
13}
transfer/event/sync

Response fields and example

transfer_events
[object]
event_id
integer
Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers.

Minimum: 0
timestamp
string
The datetime when this event occurred. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time
event_type
string
The type of event that this transfer represents.
pending: A new transfer was created; it is in the pending state.
cancelled: The transfer was cancelled by the client.
failed: The transfer failed, no funds were moved.
posted: The transfer has been successfully submitted to the payment network.
settled: Credits are available to be withdrawn or debits have been deducted from the Plaid linked account.
returned: A posted transfer was returned.
swept: The transfer was swept to / from the sweep account.
swept_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account.
return_swept: Due to the transfer being returned, funds were pulled from or pushed back to the sweep account.

Possible values: pending, cancelled, failed, posted, settled, returned, swept, swept_settled, return_swept
account_id
string
The account ID associated with the transfer.
funding_account_id
nullablestring
The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.
transfer_id
string
Plaid’s unique identifier for a transfer.
transfer_type
string
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account.

Possible values: debit, credit
transfer_amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
failure_reason
nullableobject
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.
ach_return_code
nullablestring
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.
description
string
A human-readable description of the reason for the failure or reversal.
sweep_id
nullablestring
Plaid’s unique identifier for a sweep.
sweep_amount
nullablestring
A signed amount of how much was swept or return_swept for this transfer (decimal string with two digits of precision e.g. "-5.50").
refund_id
nullablestring
Plaid’s unique identifier for a refund. A non-null value indicates the event is for the associated refund of the transfer.
originator_client_id
nullablestring
The Plaid client ID that is the originator of the transfer that this event applies to. Only present if the transfer was created on behalf of another client as a third-party sender (TPS).
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transfer_events": [
3    {
4      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
5      "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
6      "transfer_amount": "12.34",
7      "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
8      "transfer_type": "credit",
9      "event_id": 1,
10      "event_type": "pending",
11      "failure_reason": null,
12      "origination_account_id": "",
13      "originator_client_id": null,
14      "refund_id": null,
15      "sweep_amount": null,
16      "sweep_id": null,
17      "timestamp": "2019-12-09T17:27:15Z"
18    }
19  ],
20  "request_id": "mdqfuVxeoza6mhu"
21}
Was this helpful?

/transfer/sweep/get

Retrieve a sweep

The /transfer/sweep/get endpoint fetches a sweep corresponding to the given sweep_id.

transfer/sweep/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
sweep_id
requiredstring
Plaid's unique identifier for the sweep (UUID) or a shortened form consisting of the first 8 characters of the identifier (8-digit hexadecimal string).
Select Language
1const request: TransferSweepGetRequest = {
2  sweep_id: '8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee',
3};
4try {
5  const response = await plaidClient.transferSweepGet(request);
6  const sweep = response.data.sweep;
7} catch (error) {
8  // handle error
9}
transfer/sweep/get

Response fields and example

sweep
object
Describes a sweep of funds to / from the sweep account.
A sweep is associated with many sweep events (events of type swept or return_swept) which can be retrieved by invoking the /transfer/event/list endpoint with the corresponding sweep_id.
swept events occur when the transfer amount is credited or debited from your sweep account, depending on the type of the transfer. return_swept events occur when a transfer is returned and Plaid undoes the credit or debit.
The total sum of the swept and return_swept events is equal to the amount of the sweep Plaid creates and matches the amount of the entry on your sweep account ledger.
id
string
Identifier of the sweep.
funding_account_id
string
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.
created
string
The datetime when the sweep occurred, in RFC 3339 format.

Format: date-time
amount
string
Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00")
If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced.
iso_currency_code
string
The currency of the sweep, e.g. "USD".
settled
nullablestring
The date when the sweep settled, in the YYYY-MM-DD format.

Format: date
status
nullablestring
The status of a sweep transfer
"pending" - The sweep is currently pending "posted" - The sweep has been posted "settled" - The sweep has settled "returned" - The sweep has been returned "failed" - The sweep has failed

Possible values: pending, posted, settled, returned, failed, null
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "sweep": {
3    "id": "8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee",
4    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
5    "created": "2020-08-06T17:27:15Z",
6    "amount": "12.34",
7    "iso_currency_code": "USD",
8    "settled": "2020-08-07",
9    "status": "settled"
10  },
11  "request_id": "saKrIBuEB9qJZno"
12}
Was this helpful?

/transfer/sweep/list

List sweeps

The /transfer/sweep/list endpoint fetches sweeps matching the given filters.

transfer/sweep/list

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
start_date
string
The start datetime of sweeps to return (RFC 3339 format).

Format: date-time
end_date
string
The end datetime of sweeps to return (RFC 3339 format).

Format: date-time
count
integer
The maximum number of sweeps to return.

Minimum: 1
Maximum: 25
Default: 25
offset
integer
The number of sweeps to skip before returning results.

Default: 0
Minimum: 0
amount
string
Filter sweeps to only those with the specified amount.
status
string
The status of a sweep transfer
"pending" - The sweep is currently pending "posted" - The sweep has been posted "settled" - The sweep has settled "returned" - The sweep has been returned "failed" - The sweep has failed

Possible values: pending, posted, settled, returned, failed, null
originator_client_id
string
Filter sweeps to only those with the specified originator client.
funding_account_id
string
Filter sweeps to only those with the specified funding_account_id.
transfer_id
string
Filter sweeps to only those with the included transfer_id.
Select Language
1const request: TransferSweepListRequest = {
2  start_date: '2019-12-06T22:35:49Z',
3  end_date: '2019-12-12T22:35:49Z',
4  count: 14,
5  offset: 2,
6};
7try {
8  const response = await plaidClient.transferSweepList(request);
9  const sweeps = response.data.sweeps;
10  for (const sweep of sweeps) {
11    // iterate through sweeps
12  }
13} catch (error) {
14  // handle error
15}
transfer/sweep/list

Response fields and example

sweeps
[object]
id
string
Identifier of the sweep.
funding_account_id
string
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.
created
string
The datetime when the sweep occurred, in RFC 3339 format.

Format: date-time
amount
string
Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00")
If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced.
iso_currency_code
string
The currency of the sweep, e.g. "USD".
settled
nullablestring
The date when the sweep settled, in the YYYY-MM-DD format.

Format: date
status
nullablestring
The status of a sweep transfer
"pending" - The sweep is currently pending "posted" - The sweep has been posted "settled" - The sweep has settled "returned" - The sweep has been returned "failed" - The sweep has failed

Possible values: pending, posted, settled, returned, failed, null
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "sweeps": [
3    {
4      "id": "d5394a4d-0b04-4a02-9f4a-7ca5c0f52f9d",
5      "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
6      "created": "2019-12-09T17:27:15Z",
7      "amount": "-12.34",
8      "iso_currency_code": "USD",
9      "settled": "2019-12-10",
10      "status": "settled",
11      "originator_client_id": null
12    }
13  ],
14  "request_id": "saKrIBuEB9qJZno"
15}
Was this helpful?

/transfer/intent/create

Create a transfer intent object to invoke the Transfer UI

Use the /transfer/intent/create endpoint to generate a transfer intent object and invoke the Transfer UI.

transfer/intent/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
account_id
string
The Plaid account_id corresponding to the end-user account that will be debited or credited.
funding_account_id
string
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited. Defaults to the account configured during onboarding.
mode
requiredstring
The direction of the flow of transfer funds.
PAYMENT: Transfers funds from an end user's account to your business account.
DISBURSEMENT: Transfers funds from your business account to an end user's account.

Possible values: PAYMENT, DISBURSEMENT
network
string
The network or rails used for the transfer. Defaults to same-day-ach.
For transfers submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded if applicable.

Possible values: ach, same-day-ach
Default: same-day-ach
amount
requiredstring
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
description
requiredstring
A description for the underlying transfer. Maximum of 8 characters.

Min length: 1
Max length: 8
ach_class
string
Specifies the use case of the transfer. Required for transfers on an ACH network.
"ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts
"ppd" - Prearranged Payment or Deposit - the transfer is part of a pre-existing relationship with a consumer, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web
user
requiredobject
The legal name and other information for the account holder.
legal_name
requiredstring
The user's legal name.
phone_number
string
The user's phone number.
email_address
string
The user's email address.
address
object
The address associated with the account holder. Providing this data will improve the likelihood that Plaid will be able to guarantee the transfer, if applicable.
street
string
The street number and name (i.e., "100 Market St.").
city
string
Ex. "San Francisco"
region
string
The state or province (e.g., "CA").
postal_code
string
The postal code (e.g., "94103").
country
string
A two-letter country code (e.g., "US").
metadata
object
The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
Select Language
1const request: TransferIntentCreateRequest = {
2  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
3  mode: 'PAYMENT'
4  amount: '12.34',
5  description: 'Desc',
6  ach_class: 'ppd',
7  origination_account_id: '9853defc-e703-463d-86b1-dc0607a45359',
8  user: {
9    legal_name: 'Anne Charleston',
10  },
11};
12
13try {
14  const response = await client.transferIntentCreate(request);
15} catch (error) {
16  // handle error
17}
transfer/intent/create

Response fields and example

transfer_intent
object
Represents a transfer intent within Transfer UI.
id
string
Plaid's unique identifier for the transfer intent object.
created
string
The datetime the transfer was created. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time
status
string
The status of the transfer intent.
PENDING: The transfer intent is pending. SUCCEEDED: The transfer intent was successfully created. FAILED: The transfer intent was unable to be created.

Possible values: PENDING, SUCCEEDED, FAILED
account_id
nullablestring
The Plaid account_id corresponding to the end-user account that will be debited or credited. Returned only if account_id was set on intent creation.
funding_account_id
string
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.
amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
mode
string
The direction of the flow of transfer funds.
PAYMENT: Transfers funds from an end user's account to your business account.
DISBURSEMENT: Transfers funds from your business account to an end user's account.

Possible values: PAYMENT, DISBURSEMENT
network
string
The network or rails used for the transfer. Defaults to same-day-ach.
For transfers submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded if applicable.

Possible values: ach, same-day-ach
Default: same-day-ach
ach_class
string
Specifies the use case of the transfer. Required for transfers on an ACH network.
"ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts
"ppd" - Prearranged Payment or Deposit - the transfer is part of a pre-existing relationship with a consumer, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web
user
object
The legal name and other information for the account holder.
legal_name
string
The user's legal name.
phone_number
nullablestring
The user's phone number.
email_address
nullablestring
The user's email address.
address
nullableobject
The address associated with the account holder.
street
nullablestring
The street number and name (i.e., "100 Market St.").
city
nullablestring
Ex. "San Francisco"
region
nullablestring
The state or province (e.g., "CA").
postal_code
nullablestring
The postal code (e.g., "94103").
country
nullablestring
A two-letter country code (e.g., "US").
description
string
A description for the underlying transfer. Maximum of 8 characters.
metadata
nullableobject
The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transfer_intent": {
3    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
4    "funding_account_id": "9853defc-e703-463d-86b1-dc0607a45359",
5    "ach_class": "ppd",
6    "amount": "12.34",
7    "iso_currency_code": "USD",
8    "created": "2020-08-06T17:27:15Z",
9    "description": "Desc",
10    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
11    "metadata": {
12      "key1": "value1",
13      "key2": "value2"
14    },
15    "mode": "PAYMENT",
16    "origination_account_id": "9853defc-e703-463d-86b1-dc0607a45359",
17    "status": "PENDING",
18    "user": {
19      "address": {
20        "street": "100 Market Street",
21        "city": "San Francisco",
22        "region": "CA",
23        "postal_code": "94103",
24        "country": "US"
25      },
26      "email_address": "acharleston@email.com",
27      "legal_name": "Anne Charleston",
28      "phone_number": "123-456-7890"
29    }
30  },
31  "request_id": "saKrIBuEB9qJZno"
32}
Was this helpful?

/transfer/intent/get

Retrieve more information about a transfer intent

Use the /transfer/intent/get endpoint to retrieve more information about a transfer intent.

transfer/intent/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
transfer_intent_id
requiredstring
Plaid's unique identifier for a transfer intent object.
Select Language
1const request: TransferIntentGetRequest = {
2  transfer_intent_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
3};
4
5try {
6  const response = await client.transferIntentGet(request);
7} catch (error) {
8  // handle error
9}
transfer/intent/get

Response fields and example

transfer_intent
object
Represents a transfer intent within Transfer UI.
id
string
Plaid's unique identifier for a transfer intent object.
created
string
The datetime the transfer was created. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time
status
string
The status of the transfer intent.
PENDING: The transfer intent is pending. SUCCEEDED: The transfer intent was successfully created. FAILED: The transfer intent was unable to be created.

Possible values: PENDING, SUCCEEDED, FAILED
transfer_id
nullablestring
Plaid's unique identifier for the transfer created through the UI. Returned only if the transfer was successfully created. Null value otherwise.
failure_reason
nullableobject
The reason for a failed transfer intent. Returned only if the transfer intent status is failed. Null otherwise.
error_type
string
A broad categorization of the error.
error_code
string
A code representing the reason for a failed transfer intent (i.e., an API error or the authorization being declined).
error_message
string
A human-readable description of the code associated with a failed transfer intent.
authorization_decision
nullablestring
A decision regarding the proposed transfer.
APPROVED – The proposed transfer has received the end user's consent and has been approved for processing by Plaid. The decision_rationale field is set if Plaid was unable to fetch the account information. You may proceed with the transfer, but further review is recommended (i.e., use Link in update to re-authenticate your user when decision_rationale.code is ITEM_LOGIN_REQUIRED). Refer to the code field in the decision_rationale object for details.
DECLINED – Plaid reviewed the proposed transfer and declined processing. Refer to the code field in the decision_rationale object for details.

Possible values: APPROVED, DECLINED
authorization_decision_rationale
nullableobject
The rationale for Plaid's decision regarding a proposed transfer. It is always set for declined decisions, and may or may not be null for approved decisions.
code
string
A code representing the rationale for approving or declining the proposed transfer. Possible values are:
MANUALLY_VERIFIED_ITEM – Item created via same-day micro deposits, limited information available. Plaid will offer approved as a transaction decision.
ITEM_LOGIN_REQUIRED – Unable to collect the account information due to Item staleness. Can be rectified using Link in update mode. Plaid will offer approved as a transaction decision.
PAYMENT_PROFILE_LOGIN_REQUIRED - Unable to collect the account information due to invalid login when using Payment Profiles. Can be rectified using update mode for Payment Profile. Plaid will offer approved as a transaction decision.
ERROR – Unable to collect the account information due to an error. Plaid will offer approved as a transaction decision.
NSF – Transaction likely to result in a return due to insufficient funds. Plaid will offer declined as a transaction decision.
RISK - Transaction is high-risk. Plaid will offer declined as a transaction decision.
TRANSFER_LIMIT_REACHED - One or several transfer limits are reached, e.g. monthly transfer limit. Plaid will offer declined as a transaction decision.
MIGRATED_ACCOUNT_ITEM - Item created via /transfer/account_migration endpoint, limited information available. Plaid will offer approved as a transaction decision.

Possible values: NSF, RISK, TRANSFER_LIMIT_REACHED, MANUALLY_VERIFIED_ITEM, ITEM_LOGIN_REQUIRED, PAYMENT_PROFILE_LOGIN_REQUIRED, ERROR, MIGRATED_ACCOUNT_ITEM
description
string
A human-readable description of the code associated with a transfer approval or transfer decline.
account_id
nullablestring
The Plaid account_id for the account that will be debited or credited. Returned only if account_id was set on intent creation.
funding_account_id
string
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.
amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
mode
string
The direction of the flow of transfer funds.
PAYMENT: Transfers funds from an end user's account to your business account.
DISBURSEMENT: Transfers funds from your business account to an end user's account.

Possible values: PAYMENT, DISBURSEMENT
network
string
The network or rails used for the transfer. Defaults to same-day-ach.
For transfers submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded if applicable.

Possible values: ach, same-day-ach
Default: same-day-ach
ach_class
string
Specifies the use case of the transfer. Required for transfers on an ACH network.
"ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts
"ppd" - Prearranged Payment or Deposit - the transfer is part of a pre-existing relationship with a consumer, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web
user
object
The legal name and other information for the account holder.
legal_name
string
The user's legal name.
phone_number
nullablestring
The user's phone number.
email_address
nullablestring
The user's email address.
address
nullableobject
The address associated with the account holder.
street
nullablestring
The street number and name (i.e., "100 Market St.").
city
nullablestring
Ex. "San Francisco"
region
nullablestring
The state or province (e.g., "CA").
postal_code
nullablestring
The postal code (e.g., "94103").
country
nullablestring
A two-letter country code (e.g., "US").
description
string
A description for the underlying transfer. Maximum of 8 characters.
metadata
nullableobject
The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transfer_intent": {
3    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
4    "funding_account_id": "9853defc-e703-463d-86b1-dc0607a45359",
5    "ach_class": "ppd",
6    "amount": "12.34",
7    "iso_currency_code": "USD",
8    "authorization_decision": "APPROVED",
9    "authorization_decision_rationale": null,
10    "created": "2019-12-09T17:27:15Z",
11    "description": "Desc",
12    "failure_reason": null,
13    "guarantee_decision": null,
14    "guarantee_decision_rationale": null,
15    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
16    "metadata": {
17      "key1": "value1",
18      "key2": "value2"
19    },
20    "mode": "DISBURSEMENT",
21    "origination_account_id": "9853defc-e703-463d-86b1-dc0607a45359",
22    "status": "SUCCEEDED",
23    "transfer_id": "590ecd12-1dcc-7eae-4ad6-c28d1ec90df2",
24    "user": {
25      "address": {
26        "street": "123 Main St.",
27        "city": "San Francisco",
28        "region": "California",
29        "postal_code": "94053",
30        "country": "US"
31      },
32      "email_address": "acharleston@email.com",
33      "legal_name": "Anne Charleston",
34      "phone_number": "510-555-0128"
35    }
36  },
37  "request_id": "saKrIBuEB9qJZno"
38}
Was this helpful?

/transfer/recurring/create

Create a recurring transfer

Use the /transfer/recurring/create endpoint to initiate a new recurring transfer.

transfer/recurring/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The Plaid access_token for the account that will be debited or credited. Required if not using payment_profile_token.
idempotency_key
requiredstring
A random key provided by the client, per unique recurring transfer. Maximum of 50 characters.
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a recurring fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single recurring transfer is created.

Max length: 50
account_id
requiredstring
The Plaid account_id corresponding to the end-user account that will be debited or credited. Required when creating a transfer using an access_token.
funding_account_id
string
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited. Defaults to the account configured during onboarding.
type
requiredstring
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account.

Possible values: debit, credit
network
requiredstring
The network or rails used for the transfer.
For transfers submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded if applicable.

Possible values: ach, same-day-ach, rtp
ach_class
string
Specifies the use case of the transfer. Required for transfers on an ACH network.
"ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts
"ppd" - Prearranged Payment or Deposit - the transfer is part of a pre-existing relationship with a consumer, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web
amount
requiredstring
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
user_present
requiredboolean
If the end user is initiating the specific transfer themselves via an interactive UI, this should be true; for automatic recurring payments where the end user is not actually initiating each individual transfer, it should be false.
description
requiredstring
The description of the recurring transfer.
test_clock_id
string
Plaid’s unique identifier for a test clock. This field may only be used when using sandbox environment. If provided, the created recurring_transfer is associated with the test_clock. New originations are automatically generated when the associated test_clock advances.
schedule
requiredobject
The schedule that the recurring transfer will be executed on.
interval_unit
requiredstring
The unit of the recurring interval.

Possible values: week, month
Min length: 1
interval_count
requiredinteger
The number of recurring interval_units between originations. The recurring interval(before holiday adjustment) is calculated by multiplying interval_unit and interval_count. For instance, to schedule a recurring transfer which originates once every two weeks, set interval_unit = week and interval_count = 2.
interval_execution_day
requiredinteger
The day of the interval on which to schedule the transfer.
If the interval_unit is week, interval_execution_day should be an integer from 1 (Monday) to 5 (Friday).
If the interval_unit is month, interval_execution_day should be an integer indicating which day of the month to make the transfer on. Integers from 1 to 28 can be used to make a transfer on that day of the month. Negative integers from -1 to -5 can be used to make a transfer relative to the end of the month. To make a transfer on the last day of the month, use -1; to make the transfer on the second-to-last day, use -2, and so on.
The transfer will be originated on next available banking day if the designated day is a non banking day.
start_date
requiredstring
A date in ISO 8601 format (YYYY-MM-DD). The recurring transfer will begin on the first interval_execution_day on or after the start_date.
If the first interval_execution_day on or after the start date is also the same day that /transfer/recurring/create was called, the bank may make the first payment on that day, but it is not guaranteed to do so.

Format: date
end_date
string
A date in ISO 8601 format (YYYY-MM-DD). The recurring transfer will end on the last interval_execution_day on or before the end_date. If the interval_execution_day between the start date and the end date (inclusive) is also the same day that /transfer/recurring/create was called, the bank may make a payment on that day, but it is not guaranteed to do so.

Format: date
user
requiredobject
The legal name and other information for the account holder.
legal_name
requiredstring
The user's legal name.
phone_number
string
The user's phone number.
email_address
string
The user's email address.
address
object
The address associated with the account holder. Providing this data will improve the likelihood that Plaid will be able to guarantee the transfer, if applicable.
street
string
The street number and name (i.e., "100 Market St.").
city
string
Ex. "San Francisco"
region
string
The state or province (e.g., "CA").
postal_code
string
The postal code (e.g., "94103").
country
string
A two-letter country code (e.g., "US").
device
requiredobject
Information about the device being used to initiate the authorization.
ip_address
requiredstring
The IP address of the device being used to initiate the authorization.
user_agent
requiredstring
The user agent of the device being used to initiate the authorization.
Select Language
1const request: TransferRecurringCreateRequest = {
2  access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
3  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
4  type: 'credit',
5  network: 'ach',
6  amount: '12.34',
7  ach_class: 'ppd',
8  description: 'payment',
9  idempotency_key: '12345',
10  schedule: {
11    start_date: '2022-10-01',
12    end_date: '20223-10-01',
13    interval_unit: 'week',
14    interval_count: 1,
15    interval_execution_day: 5
16  }
17  user: {
18    legal_name: 'Anne Charleston',
19  },
20};
21
22try {
23  const response = await client.transferRecurringCreate(request);
24  const recurringTransferId = response.data.recurring_transfer.recurring_transfer_id;
25} catch (error) {
26  // handle error
27}
transfer/recurring/create

Response fields and example

recurring_transfer
nullableobject
Represents a recurring transfer within the Transfers API.
recurring_transfer_id
string
Plaid’s unique identifier for a recurring transfer.
created
string
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
next_origination_date
nullablestring
A date in ISO 8601 format (YYYY-MM-DD).
The next transfer origination date after bank holiday adjustment.

Format: date
test_clock_id
nullablestring
Plaid’s unique identifier for a test clock.
type
string
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account.

Possible values: debit, credit
amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
status
string
The status of the recurring transfer.
active: The recurring transfer is currently active. cancelled: The recurring transfer was cancelled by the client or Plaid. expired: The recurring transfer has completed all originations according to its recurring schedule.

Possible values: active, cancelled, expired
ach_class
string
Specifies the use case of the transfer. Required for transfers on an ACH network.
"ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts
"ppd" - Prearranged Payment or Deposit - the transfer is part of a pre-existing relationship with a consumer, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web
network
string
The network or rails used for the transfer.
For transfers submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded if applicable.

Possible values: ach, same-day-ach, rtp
account_id
string
The Plaid account_id corresponding to the end-user account that will be debited or credited.
funding_account_id
string
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
description
string
The description of the recurring transfer.
transfer_ids
[string]
user
object
The legal name and other information for the account holder.
legal_name
string
The user's legal name.
phone_number
nullablestring
The user's phone number.
email_address
nullablestring
The user's email address.
address
nullableobject
The address associated with the account holder.
street
nullablestring
The street number and name (i.e., "100 Market St.").
city
nullablestring
Ex. "San Francisco"
region
nullablestring
The state or province (e.g., "CA").
postal_code
nullablestring
The postal code (e.g., "94103").
country
nullablestring
A two-letter country code (e.g., "US").
schedule
object
The schedule that the recurring transfer will be executed on.
interval_unit
string
The unit of the recurring interval.

Possible values: week, month
Min length: 1
interval_count
integer
The number of recurring interval_units between originations. The recurring interval(before holiday adjustment) is calculated by multiplying interval_unit and interval_count. For instance, to schedule a recurring transfer which originates once every two weeks, set interval_unit = week and interval_count = 2.
interval_execution_day
integer
The day of the interval on which to schedule the transfer.
If the interval_unit is week, interval_execution_day should be an integer from 1 (Monday) to 5 (Friday).
If the interval_unit is month, interval_execution_day should be an integer indicating which day of the month to make the transfer on. Integers from 1 to 28 can be used to make a transfer on that day of the month. Negative integers from -1 to -5 can be used to make a transfer relative to the end of the month. To make a transfer on the last day of the month, use -1; to make the transfer on the second-to-last day, use -2, and so on.
The transfer will be originated on next available banking day if the designated day is a non banking day.
start_date
string
A date in ISO 8601 format (YYYY-MM-DD). The recurring transfer will begin on the first interval_execution_day on or after the start_date.
If the first interval_execution_day on or after the start date is also the same day that /transfer/recurring/create was called, the bank may make the first payment on that day, but it is not guaranteed to do so.

Format: date
end_date
nullablestring
A date in ISO 8601 format (YYYY-MM-DD). The recurring transfer will end on the last interval_execution_day on or before the end_date. If the interval_execution_day between the start date and the end date (inclusive) is also the same day that /transfer/recurring/create was called, the bank may make a payment on that day, but it is not guaranteed to do so.

Format: date
decision
string
A decision regarding the proposed transfer.
approved – The proposed transfer has received the end user's consent and has been approved for processing by Plaid. The decision_rationale field is set if Plaid was unable to fetch the account information. You may proceed with the transfer, but further review is recommended (i.e., use Link in update to re-authenticate your user when decision_rationale.code is ITEM_LOGIN_REQUIRED). Refer to the code field in the decision_rationale object for details.
declined – Plaid reviewed the proposed transfer and declined processing. Refer to the code field in the decision_rationale object for details.

Possible values: approved, declined
decision_rationale
nullableobject
The rationale for Plaid's decision regarding a proposed transfer. It is always set for declined decisions, and may or may not be null for approved decisions.
code
string
A code representing the rationale for approving or declining the proposed transfer. Possible values are:
MANUALLY_VERIFIED_ITEM – Item created via same-day micro deposits, limited information available. Plaid will offer approved as a transaction decision.
ITEM_LOGIN_REQUIRED – Unable to collect the account information due to Item staleness. Can be rectified using Link in update mode. Plaid will offer approved as a transaction decision.
PAYMENT_PROFILE_LOGIN_REQUIRED - Unable to collect the account information due to invalid login when using Payment Profiles. Can be rectified using update mode for Payment Profile. Plaid will offer approved as a transaction decision.
ERROR – Unable to collect the account information due to an error. Plaid will offer approved as a transaction decision.
NSF – Transaction likely to result in a return due to insufficient funds. Plaid will offer declined as a transaction decision.
RISK - Transaction is high-risk. Plaid will offer declined as a transaction decision.
TRANSFER_LIMIT_REACHED - One or several transfer limits are reached, e.g. monthly transfer limit. Plaid will offer declined as a transaction decision.
MIGRATED_ACCOUNT_ITEM - Item created via /transfer/account_migration endpoint, limited information available. Plaid will offer approved as a transaction decision.

Possible values: NSF, RISK, TRANSFER_LIMIT_REACHED, MANUALLY_VERIFIED_ITEM, ITEM_LOGIN_REQUIRED, PAYMENT_PROFILE_LOGIN_REQUIRED, ERROR, MIGRATED_ACCOUNT_ITEM
description
string
A human-readable description of the code associated with a transfer approval or transfer decline.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "recurring_transfer": {
3    "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
4    "created": "2022-07-05T12:48:37Z",
5    "next_origination_date": "2022-10-28",
6    "test_clock_id": "b33a6eda-5e97-5d64-244a-a9274110151c",
7    "status": "active",
8    "amount": "12.34",
9    "description": "payment",
10    "type": "debit",
11    "ach_class": "ppd",
12    "network": "ach",
13    "origination_account_id": "",
14    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
15    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
16    "iso_currency_code": "USD",
17    "transfer_ids": [],
18    "user": {
19      "legal_name": "Anne Charleston",
20      "phone_number": "510-555-0128",
21      "email_address": "acharleston@email.com",
22      "address": {
23        "street": "123 Main St.",
24        "city": "San Francisco",
25        "region": "CA",
26        "postal_code": "94053",
27        "country": "US"
28      }
29    },
30    "schedule": {
31      "start_date": "2022-10-01",
32      "end_date": "2023-10-01",
33      "interval_unit": "week",
34      "interval_count": 1,
35      "interval_execution_day": 5
36    }
37  },
38  "decision": "approved",
39  "decision_rationale": null,
40  "request_id": "saKrIBuEB9qJZno"
41}
Was this helpful?

/transfer/recurring/cancel

Cancel a recurring transfer.

Use the /transfer/recurring/cancel endpoint to cancel a recurring transfer. Scheduled transfer that hasn't been submitted to bank will be cancelled.

transfer/recurring/cancel

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
recurring_transfer_id
requiredstring
Plaid’s unique identifier for a recurring transfer.
Select Language
1const request: TransferRecurringCancelRequest = {
2  recurring_transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
3};
4
5try {
6  const response = await client.transferRecurringCancel(request);
7} catch (error) {
8  // handle error
9}
transfer/recurring/cancel

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "saKrIBuEB9qJZno"
3}
Was this helpful?

/transfer/recurring/get

Retrieve a recurring transfer

The /transfer/recurring/get fetches information about the recurring transfer corresponding to the given recurring_transfer_id.

transfer/recurring/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
recurring_transfer_id
requiredstring
Plaid’s unique identifier for a recurring transfer.
Select Language
1const request: TransferRecurringGetRequest = {
2  recurring_transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
3};
4
5try {
6  const response = await client.transferRecurringGet(request);
7  const recurringTransferId =
8    response.data.recurring_transfer.recurring_transfer_id;
9} catch (error) {
10  // handle error
11}
transfer/recurring/get

Response fields and example

recurring_transfer
object
Represents a recurring transfer within the Transfers API.
recurring_transfer_id
string
Plaid’s unique identifier for a recurring transfer.
created
string
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
next_origination_date
nullablestring
A date in ISO 8601 format (YYYY-MM-DD).
The next transfer origination date after bank holiday adjustment.

Format: date
test_clock_id
nullablestring
Plaid’s unique identifier for a test clock.
type
string
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account.

Possible values: debit, credit
amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
status
string
The status of the recurring transfer.
active: The recurring transfer is currently active. cancelled: The recurring transfer was cancelled by the client or Plaid. expired: The recurring transfer has completed all originations according to its recurring schedule.

Possible values: active, cancelled, expired
ach_class
string
Specifies the use case of the transfer. Required for transfers on an ACH network.
"ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts
"ppd" - Prearranged Payment or Deposit - the transfer is part of a pre-existing relationship with a consumer, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web
network
string
The network or rails used for the transfer.
For transfers submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded if applicable.

Possible values: ach, same-day-ach, rtp
account_id
string
The Plaid account_id corresponding to the end-user account that will be debited or credited.
funding_account_id
string
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
description
string
The description of the recurring transfer.
transfer_ids
[string]
user
object
The legal name and other information for the account holder.
legal_name
string
The user's legal name.
phone_number
nullablestring
The user's phone number.
email_address
nullablestring
The user's email address.
address
nullableobject
The address associated with the account holder.
street
nullablestring
The street number and name (i.e., "100 Market St.").
city
nullablestring
Ex. "San Francisco"
region
nullablestring
The state or province (e.g., "CA").
postal_code
nullablestring
The postal code (e.g., "94103").
country
nullablestring
A two-letter country code (e.g., "US").
schedule
object
The schedule that the recurring transfer will be executed on.
interval_unit
string
The unit of the recurring interval.

Possible values: week, month
Min length: 1
interval_count
integer
The number of recurring interval_units between originations. The recurring interval(before holiday adjustment) is calculated by multiplying interval_unit and interval_count. For instance, to schedule a recurring transfer which originates once every two weeks, set interval_unit = week and interval_count = 2.
interval_execution_day
integer
The day of the interval on which to schedule the transfer.
If the interval_unit is week, interval_execution_day should be an integer from 1 (Monday) to 5 (Friday).
If the interval_unit is month, interval_execution_day should be an integer indicating which day of the month to make the transfer on. Integers from 1 to 28 can be used to make a transfer on that day of the month. Negative integers from -1 to -5 can be used to make a transfer relative to the end of the month. To make a transfer on the last day of the month, use -1; to make the transfer on the second-to-last day, use -2, and so on.
The transfer will be originated on next available banking day if the designated day is a non banking day.
start_date
string
A date in ISO 8601 format (YYYY-MM-DD). The recurring transfer will begin on the first interval_execution_day on or after the start_date.
If the first interval_execution_day on or after the start date is also the same day that /transfer/recurring/create was called, the bank may make the first payment on that day, but it is not guaranteed to do so.

Format: date
end_date
nullablestring
A date in ISO 8601 format (YYYY-MM-DD). The recurring transfer will end on the last interval_execution_day on or before the end_date. If the interval_execution_day between the start date and the end date (inclusive) is also the same day that /transfer/recurring/create was called, the bank may make a payment on that day, but it is not guaranteed to do so.

Format: date
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "recurring_transfer": {
3    "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
4    "created": "2022-07-05T12:48:37Z",
5    "next_origination_date": "2022-10-28",
6    "test_clock_id": null,
7    "status": "active",
8    "amount": "12.34",
9    "description": "payment",
10    "type": "debit",
11    "ach_class": "ppd",
12    "network": "ach",
13    "origination_account_id": "",
14    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
15    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
16    "iso_currency_code": "USD",
17    "transfer_ids": [
18      "271ef220-dbf8-caeb-a7dc-a2b3e8a80963",
19      "c8dbaf75-2abb-e2dc-4171-12448e13b848"
20    ],
21    "user": {
22      "legal_name": "Anne Charleston",
23      "phone_number": "510-555-0128",
24      "email_address": "acharleston@email.com",
25      "address": {
26        "street": "123 Main St.",
27        "city": "San Francisco",
28        "region": "CA",
29        "postal_code": "94053",
30        "country": "US"
31      }
32    },
33    "schedule": {
34      "start_date": "2022-10-01",
35      "end_date": "2023-10-01",
36      "interval_unit": "week",
37      "interval_count": 1,
38      "interval_execution_day": 5
39    }
40  },
41  "request_id": "saKrIBuEB9qJZno"
42}
Was this helpful?

/transfer/recurring/list

List recurring transfers

Use the /transfer/recurring/list endpoint to see a list of all your recurring transfers and their statuses. Results are paginated; use the count and offset query parameters to retrieve the desired recurring transfers.

transfer/recurring/list

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
start_time
string
The start datetime of recurring transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time
end_time
string
The end datetime of recurring transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time
count
integer
The maximum number of recurring transfers to return.

Minimum: 1
Maximum: 25
Default: 25
offset
integer
The number of recurring transfers to skip before returning results.

Default: 0
Minimum: 0
funding_account_id
string
Filter recurring transfers to only those with the specified funding_account_id.
Select Language
1const request: TransferRecurringListRequest = {
2  start_time: '2022-09-29T20:35:49Z',
3  end_time: '2022-10-29T20:35:49Z',
4  count: 1,
5};
6
7try {
8  const response = await client.transferRecurringList(request);
9} catch (error) {
10  // handle error
11}
transfer/recurring/list

Response fields and example

recurring_transfers
[object]
recurring_transfer_id
string
Plaid’s unique identifier for a recurring transfer.
created
string
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
next_origination_date
nullablestring
A date in ISO 8601 format (YYYY-MM-DD).
The next transfer origination date after bank holiday adjustment.

Format: date
test_clock_id
nullablestring
Plaid’s unique identifier for a test clock.
type
string
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account.

Possible values: debit, credit
amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
status
string
The status of the recurring transfer.
active: The recurring transfer is currently active. cancelled: The recurring transfer was cancelled by the client or Plaid. expired: The recurring transfer has completed all originations according to its recurring schedule.

Possible values: active, cancelled, expired
ach_class
string
Specifies the use case of the transfer. Required for transfers on an ACH network.
"ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts
"ppd" - Prearranged Payment or Deposit - the transfer is part of a pre-existing relationship with a consumer, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web
network
string
The network or rails used for the transfer.
For transfers submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded if applicable.

Possible values: ach, same-day-ach, rtp
account_id
string
The Plaid account_id corresponding to the end-user account that will be debited or credited.
funding_account_id
string
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
description
string
The description of the recurring transfer.
transfer_ids
[string]
user
object
The legal name and other information for the account holder.
legal_name
string
The user's legal name.
phone_number
nullablestring
The user's phone number.
email_address
nullablestring
The user's email address.
address
nullableobject
The address associated with the account holder.
street
nullablestring
The street number and name (i.e., "100 Market St.").
city
nullablestring
Ex. "San Francisco"
region
nullablestring
The state or province (e.g., "CA").
postal_code
nullablestring
The postal code (e.g., "94103").
country
nullablestring
A two-letter country code (e.g., "US").
schedule
object
The schedule that the recurring transfer will be executed on.
interval_unit
string
The unit of the recurring interval.

Possible values: week, month
Min length: 1
interval_count
integer
The number of recurring interval_units between originations. The recurring interval(before holiday adjustment) is calculated by multiplying interval_unit and interval_count. For instance, to schedule a recurring transfer which originates once every two weeks, set interval_unit = week and interval_count = 2.
interval_execution_day
integer
The day of the interval on which to schedule the transfer.
If the interval_unit is week, interval_execution_day should be an integer from 1 (Monday) to 5 (Friday).
If the interval_unit is month, interval_execution_day should be an integer indicating which day of the month to make the transfer on. Integers from 1 to 28 can be used to make a transfer on that day of the month. Negative integers from -1 to -5 can be used to make a transfer relative to the end of the month. To make a transfer on the last day of the month, use -1; to make the transfer on the second-to-last day, use -2, and so on.
The transfer will be originated on next available banking day if the designated day is a non banking day.
start_date
string
A date in ISO 8601 format (YYYY-MM-DD). The recurring transfer will begin on the first interval_execution_day on or after the start_date.
If the first interval_execution_day on or after the start date is also the same day that /transfer/recurring/create was called, the bank may make the first payment on that day, but it is not guaranteed to do so.

Format: date
end_date
nullablestring
A date in ISO 8601 format (YYYY-MM-DD). The recurring transfer will end on the last interval_execution_day on or before the end_date. If the interval_execution_day between the start date and the end date (inclusive) is also the same day that /transfer/recurring/create was called, the bank may make a payment on that day, but it is not guaranteed to do so.

Format: date
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "recurring_transfers": [
3    {
4      "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
5      "created": "2022-07-05T12:48:37Z",
6      "next_origination_date": "2022-10-28",
7      "test_clock_id": null,
8      "status": "active",
9      "amount": "12.34",
10      "description": "payment",
11      "type": "debit",
12      "ach_class": "ppd",
13      "network": "ach",
14      "origination_account_id": "",
15      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
16      "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
17      "iso_currency_code": "USD",
18      "transfer_ids": [
19        "4242fc8d-3ec6-fb38-fa0c-a8e37d03cd57"
20      ],
21      "user": {
22        "legal_name": "Anne Charleston",
23        "phone_number": "510-555-0128",
24        "email_address": "acharleston@email.com",
25        "address": {
26          "street": "123 Main St.",
27          "city": "San Francisco",
28          "region": "CA",
29          "postal_code": "94053",
30          "country": "US"
31        }
32      },
33      "schedule": {
34        "start_date": "2022-10-01",
35        "end_date": "2023-10-01",
36        "interval_unit": "week",
37        "interval_count": 1,
38        "interval_execution_day": 5
39      }
40    }
41  ],
42  "request_id": "saKrIBuEB9qJZno"
43}
Was this helpful?

/transfer/refund/create

Create a refund

Use the /transfer/refund/create endpoint to create a refund for a transfer. A transfer can be refunded if the transfer was initiated in the past 180 days.
Processing of the refund will not occur until at least 3 business days following the transfer's settlement date, plus any hold/settlement delays. This 3-day window helps better protect your business from regular ACH returns. Consumer initiated returns (unauthorized returns) could still happen for about 60 days from the settlement date. If the original transfer is canceled, returned or failed, all pending refunds will automatically be canceled. Processed refunds cannot be revoked.

transfer/refund/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
transfer_id
requiredstring
The ID of the transfer to refund.
amount
requiredstring
The amount of the refund (decimal string with two digits of precision e.g. "10.00").
idempotency_key
requiredstring
A random key provided by the client, per unique refund. Maximum of 50 characters.
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a refund fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single refund is created.

Max length: 50
Select Language
1const request: TransferRefundCreateRequest = {
2  transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
3  amount: '12.34',
4  idempotency_key: 'VEK2ea3X6LKywsc8J6pg',
5};
6
7try {
8  const response = await client.transferRefundCreate(request);
9} catch (error) {
10  // handle error
11}
transfer/refund/create

Response fields and example

refund
object
Represents a refund within the Transfers API.
id
string
Plaid’s unique identifier for a refund.
transfer_id
string
The ID of the transfer to refund.
amount
string
The amount of the refund (decimal string with two digits of precision e.g. "10.00").
status
string
The status of the refund.
pending: A new refund was created; it is in the pending state. posted: The refund has been successfully submitted to the payment network. settled: Credits have been refunded to the Plaid linked account. cancelled: The refund was cancelled by the client. failed: The refund has failed. returned: The refund was returned.

Possible values: pending, posted, cancelled, failed, settled, returned
failure_reason
nullableobject
The failure reason if the event type for a refund is "failed" or "returned". Null value otherwise.
ach_return_code
nullablestring
The ACH return code, e.g. R01. A return code will be provided if and only if the refund status is returned. For a full listing of ACH return codes, see Transfer errors.
description
string
A human-readable description of the reason for the failure or reversal.
created
string
The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "refund": {
3    "id": "667af684-9ee1-4f5f-862a-633ec4c545cc",
4    "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
5    "amount": "12.34",
6    "status": "pending",
7    "created": "2020-08-06T17:27:15Z",
8    "failure_reason": null
9  },
10  "request_id": "saKrIBuEB9qJZno"
11}
Was this helpful?

/transfer/refund/cancel

Cancel a refund

Use the /transfer/refund/cancel endpoint to cancel a refund. A refund is eligible for cancellation if it has not yet been submitted to the payment network.

transfer/refund/cancel

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
refund_id
requiredstring
Plaid’s unique identifier for a refund.
Select Language
1const request: TransferRefundCancelRequest = {
2  refund_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
3};
4
5try {
6  const response = await client.transferRefundCancel(request);
7} catch (error) {
8  // handle error
9}
transfer/refund/cancel

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "saKrIBuEB9qJZno"
3}
Was this helpful?

/transfer/refund/get

Retrieve a refund

The /transfer/refund/get endpoint fetches information about the refund corresponding to the given refund_id.

transfer/refund/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
refund_id
requiredstring
Plaid’s unique identifier for a refund.
Select Language
1const request: TransferRefundGetRequest = {
2  refund_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
3};
4
5try {
6  const response = await client.transferRefundGet(request);
7} catch (error) {
8  // handle error
9}
transfer/refund/get

Response fields and example

refund
object
Represents a refund within the Transfers API.
id
string
Plaid’s unique identifier for a refund.
transfer_id
string
The ID of the transfer to refund.
amount
string
The amount of the refund (decimal string with two digits of precision e.g. "10.00").
status
string
The status of the refund.
pending: A new refund was created; it is in the pending state. posted: The refund has been successfully submitted to the payment network. settled: Credits have been refunded to the Plaid linked account. cancelled: The refund was cancelled by the client. failed: The refund has failed. returned: The refund was returned.

Possible values: pending, posted, cancelled, failed, settled, returned
failure_reason
nullableobject
The failure reason if the event type for a refund is "failed" or "returned". Null value otherwise.
ach_return_code
nullablestring
The ACH return code, e.g. R01. A return code will be provided if and only if the refund status is returned. For a full listing of ACH return codes, see Transfer errors.
description
string
A human-readable description of the reason for the failure or reversal.
created
string
The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "refund": {
3    "id": "667af684-9ee1-4f5f-862a-633ec4c545cc",
4    "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
5    "amount": "12.34",
6    "status": "pending",
7    "created": "2020-08-06T17:27:15Z",
8    "failure_reason": null
9  },
10  "request_id": "saKrIBuEB9qJZno"
11}
Was this helpful?

/transfer/migrate_account

Migrate account into Transfers

As an alternative to adding Items via Link, you can also use the /transfer/migrate_account endpoint to migrate known account and routing numbers to Plaid Items. Note that Items created in this way are not compatible with endpoints for other products, such as /accounts/balance/get, and can only be used with Transfer endpoints. If you require access to other endpoints, create the Item through Link instead. Access to /transfer/migrate_account is not enabled by default; to obtain access, contact your Plaid Account Manager.

transfer/migrate_account

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
account_number
requiredstring
The user's account number.
routing_number
requiredstring
The user's routing number.
wire_routing_number
string
The user's wire transfer routing number. This is the ABA number; for some institutions, this may differ from the ACH number used in routing_number.
account_type
requiredstring
The type of the bank account (checking or savings).
Select Language
1const request: TransferMigrateAccountRequest = {
2  account_number: '100000000',
3  routing_number: '121122676',
4  account_type: 'checking',
5};
6try {
7  const response = await plaidClient.transferMigrateAccount(request);
8  const access_token = response.data.access_token;
9} catch (error) {
10  // handle error
11}
transfer/migrate_account

Response fields and example

access_token
string
The Plaid access_token for the newly created Item.
account_id
string
The Plaid account_id for the newly created Item.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "access_token": "access-sandbox-435beced-94e8-4df3-a181-1dde1cfa19f0",
3  "account_id": "zvyDgbeeDluZ43AJP6m5fAxDlgoZXDuoy5gjN",
4  "request_id": "mdqfuVxeoza6mhu"
5}
Was this helpful?

/payment_profile/create

Create payment profile

Use /payment_profile/create endpoint to create a new payment profile. To initiate the account linking experience, call /link/token/create and provide the payment_profile_token in the transfer.payment_profile_token field. You can then use the payment_profile_token when creating transfers using /transfer/authorization/create and /transfer/create.

payment_profile/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
Select Language
1const request: PaymentProfileCreateRequest = {};
2
3try {
4  const response = await client.paymentProfileCreateRequest(request);
5  const paymentProfileToken = response.data.payment_profile_token;
6} catch (error) {
7  // handle error
8}
payment_profile/create

Response fields and example

payment_profile_token
string
A payment profile token associated with the Payment Profile data that is being requested.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "payment_profile_token": "payment-profile-sandbox-eda0b25e-8ef3-4ebb-9ef7-1ef3db3c5ee8",
3  "request_id": "4ciYmmesdqSiUAB"
4}
Was this helpful?

/payment_profile/remove

Remove payment profile

Use the /payment_profile/remove endpoint to remove a given Payment Profile. Once it’s removed, it can no longer be used to create transfers.

payment_profile/remove

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
payment_profile_token
requiredstring
A payment profile token associated with the Payment Profile data that is being requested.
Select Language
1const request: PaymentProfileRemoveRequest = {
2  payment_profile_token:
3    'payment-profile-sandbox-8b66ac67-b9ee-4084-9f72-ceb4ffb2e914',
4};
5
6try {
7  const response = await client.paymentProfileRemoveRequest(request);
8} catch (error) {
9  // handle error
10}
payment_profile/remove

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "4ciYmmesdqSiUAB"
3}
Was this helpful?

/payment_profile/get

Get payment profile

Use /payment_profile/get endpoint to get the status of a given Payment Profile.

payment_profile/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
payment_profile_token
requiredstring
A payment profile token associated with the Payment Profile data that is being requested.
Select Language
1const request: PaymentProfileGetRequest = {
2  payment_profile_token:
3    'payment-profile-sandbox-8b66ac67-b9ee-4084-9f72-ceb4ffb2e914',
4};
5
6try {
7  const response = await client.paymentProfileGetRequest(request);
8  const status = response.data.status;
9} catch (error) {
10  // handle error
11}
payment_profile/get

Response fields and example

updated_at
string
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the given Payment Profile was updated at

Format: date-time
created_at
string
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the time the given Payment Profile was created at

Format: date-time
deleted_at
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the time the given Payment Profile was deleted at. Always null if the Payment Profile has not been deleted

Format: date-time
status
string
The status of the given Payment Profile.
READY: This Payment Profile is ready to be used to create transfers using /transfer/authorization/create and /transfer/create.
PENDING: This Payment Profile is not ready to be used. You’ll need to call /link/token/create and provide the payment_profile_token in the transfer.payment_profile_token field to initiate the account linking experience.
REMOVED: This Payment Profile has been removed.

Possible values: PENDING, READY, REMOVED
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "status": "READY",
3  "updated_at": "2022-07-07T12:48:37Z",
4  "created_at": "2022-07-05T12:48:37Z",
5  "deleted_at": null,
6  "request_id": "4ciYmmesdqSiUAB"
7}
Was this helpful?

/transfer/originator/create

Create a new originator

Use the /transfer/originator/create endpoint to create a new originator and return an originator_client_id.

transfer/originator/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
company_name
requiredstring
The company name of the end customer being created. This will be displayed in public-facing surfaces, e.g. Plaid Dashboard.

Min length: 1
Select Language
1const request: TransferOriginatorCreateRequest = {
2  company_name: 'Marketplace of Shannon',
3};
4
5try {
6  const response = await client.transferOriginatorCreate(request);
7} catch (error) {
8  // handle error
9}
transfer/originator/create

Response fields and example

originator_client_id
string
Client ID of the originator. This identifier will be used when creating transfers and should be stored associated with end user information.
company_name
string
The company name of the end customer.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "originator_client_id": "6a65dh3d1h0d1027121ak184",
3  "company_name": "Marketplace of Shannon",
4  "request_id": "4zlKapIkTm8p5KM"
5}
Was this helpful?

/transfer/originator/get

Get status of an originator's onboarding

The /transfer/originator/get endpoint gets status updates for an originator's onboarding process. This information is also available via the Transfer page on the Plaid dashboard.

transfer/originator/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
originator_client_id
requiredstring
Client ID of the end customer (i.e. the originator).
Select Language
1const request: TransferOriginatorGetRequest = {
2  originator_client_id: '6a65dh3d1h0d1027121ak184',
3};
4
5try {
6  const response = await client.transferOriginatorGet(request);
7} catch (error) {
8  // handle error
9}
transfer/originator/get

Response fields and example

originator
object
Originator and their status.
client_id
string
Originator’s client ID.
transfer_diligence_status
string
Originator’s diligence status.

Possible values: under_review, approved, denied
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "originator": {
3    "client_id": "6a65dh3d1h0d1027121ak184",
4    "transfer_diligence_status": "approved",
5    "company_name": "Plaid"
6  },
7  "request_id": "saKrIBuEB9qJZno"
8}
Was this helpful?

/transfer/originator/list

Get status of all originators' onboarding

The /transfer/originator/list endpoint gets status updates for all of your originators' onboarding. This information is also available via the Plaid dashboard.

transfer/originator/list

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
count
integer
The maximum number of originators to return.

Maximum: 25
Minimum: 1
Default: 25
offset
integer
The number of originators to skip before returning results.

Minimum: 0
Default: 0
Select Language
1const request: TransferOriginatorListRequest = {
2  count: 14,
3  offset: 2,
4};
5
6try {
7  const response = await client.transferOriginatorList(request);
8} catch (error) {
9  // handle error
10}
transfer/originator/list

Response fields and example

originators
[object]
client_id
string
Originator’s client ID.
transfer_diligence_status
string
Originator’s diligence status.

Possible values: under_review, approved, denied
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "originators": [
3    {
4      "client_id": "6a65dh3d1h0d1027121ak184",
5      "transfer_diligence_status": "approved"
6    },
7    {
8      "client_id": "8g89as4d2k1d9852938ba019",
9      "transfer_diligence_status": "denied"
10    }
11  ],
12  "request_id": "4zlKapIkTm8p5KM"
13}
Was this helpful?

/transfer/questionnaire/create

Generate a Plaid-hosted onboarding UI URL.

The /transfer/questionnaire/create endpoint generates a Plaid-hosted onboarding UI URL. Redirect the originator to this URL to provide their due diligence information and agree to Plaid’s terms for ACH money movement.

transfer/questionnaire/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
originator_client_id
requiredstring
Client ID of the end customer.
redirect_uri
requiredstring
URL the end customer will be redirected to after completing questions in Plaid-hosted onboarding flow.
Select Language
1const request: TransferQuestionnaireCreateRequest = {
2  originator_client_id: '6a65dh3d1h0d1027121ak184',
3  redirect_uri: 'https://example.com',
4};
5
6try {
7  const response = await client.transferQuestionnaireCreate(request);
8} catch (error) {
9  // handle error
10}
transfer/questionnaire/create

Response fields and example

onboarding_url
string
Plaid-hosted onboarding URL that you will redirect the end customer to.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "onboarding_url": "https://plaid.com/originator/hIFGXx1zM5pFerygu7lw",
3  "request_id": "saKrIBuEB9qJZno"
4}
Was this helpful?

/transfer/diligence/submit

Submit transfer diligence on behalf of the end customer (i.e. the originator).

Use the /transfer/diligence/submit endpoint to submit transfer diligence on behalf of the originator.

transfer/diligence/submit

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
originator_client_id
requiredstring
Client ID of the the originator whose diligence that you want to submit.
originator_diligence
requiredobject
The diligence information for the originator.
dba
requiredstring
The business name of the originator.
tax_id
requiredstring
The tax ID of the originator.

Min length: 1
credit_usage_configuration
object
Specifies the originator's expected usage of credits. For all dollar amounts, use a decimal string with two digits of precision e.g. "10.00". This field is required if the originator is expected to process credit transfers.
expected_frequency
requiredstring
The originator's expected transfer frequency.

Possible values: once_per_month, twice_per_month, once_per_week, daily
expected_highest_amount
requiredstring
The originator’s expected highest amount for a single credit transfer.
expected_average_amount
requiredstring
The originator’s expected average amount per credit.
expected_monthly_amount
requiredstring
The originator’s monthly expected ACH credit processing amount for the next 6-12 months.
sec_codes
required[string]
Specifies the expected use cases for the originator’s credit transfers. This should be a list that contains one or more of the following codes:
"ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts
"ppd" - Prearranged Payment or Deposit - the transfer is part of a pre-existing relationship with a consumer, eg. bill payment
"web" - A credit Entry initiated by or on behalf of a holder of a Consumer Account that is intended for a Consumer Account of a Receiver

Possible values: ccd, ppd, web
debit_usage_configuration
object
Specifies the originator's expected usage of debits. For all dollar amounts, use a decimal string with two digits of precision e.g. "10.00". This field is required if the originator is expected to process debit transfers.
expected_frequency
requiredstring
The originator's expected transfer frequency.

Possible values: once_per_month, twice_per_month, once_per_week, daily
expected_highest_amount
requiredstring
The originator’s expected highest amount for a single debit transfer.
expected_average_amount
requiredstring
The originator’s expected average amount per debit.
expected_monthly_amount
requiredstring
The originator’s monthly expected ACH debit processing amount for the next 6-12 months.
sec_codes
required[string]
Specifies the expected use cases for the originator’s debit transfers. This should be a list that contains one or more of the following codes:
"ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts
"ppd" - Prearranged Payment or Deposit - the transfer is part of a pre-existing relationship with a consumer, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web
address
requiredobject
The originator's address.
city
requiredstring
street
requiredstring
region
requiredstring
postal_code
requiredstring
country_code
requiredstring
ISO-3166-1 alpha-2 country code standard.
website
requiredstring
The website of the originator.
naics_code
requiredstring
The NAICS code of the originator.

Min length: 6
Max length: 6
Select Language
1const request: TransferDiligenceSubmitRequest = {
2  originator_client_id: '415ab64b87ec47401d000002',
3  originator_diligence: {
4    address: {
5      city: 'San Francisco',
6      country_code: 'US',
7      postal_code: '95302',
8      region: 'San Francisco',
9      street: '1 A street',
10    },
11    dba: 'Marketplace of Shannon',
12    credit_usage_configuration: {
13      expected_average_amount: '10.00',
14      expected_frequency: 'once_per_week',
15      expected_highest_amount: '100.00',
16      expected_monthly_amount: '1000.00',
17      sec_codes: ['ccd', 'ppd'],
18    },
19    debit_usage_configuration: {
20      expected_average_amount: '10.00',
21      expected_frequency: 'once_per_week',
22      expected_highest_amount: '100.00',
23      expected_monthly_amount: '1000.00',
24      sec_codes: ['ccd', 'ppd'],
25    },
26    naics_code: '111111',
27    tax_id: '123456789',
28    website: 'www.website.com',
29  },
30};
31
32try {
33  const response = await client.transferDiligenceSubmit(request);
34} catch (error) {
35  // handle error
36}
transfer/diligence/submit

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "4zlKapIkTm8p5KM"
3}
Was this helpful?

/transfer/diligence/document/upload

This endpoint allows third-party sender customers to upload a document on behalf of its end customer (i.e. originator) to Plaid. You’ll need to send a request of type multipart/form-data.

Third-party sender customers can use /transfer/diligence/document/upload endpoint to upload a document on behalf of its end customer (i.e. originator) to Plaid. You’ll need to send a request of type multipart/form-data. You must provide the client_id in the PLAID-CLIENT-ID header and secret in the PLAID-SECRET header.

transfer/diligence/document/upload

Request fields and example

originator_client_id
requiredstring
The Client ID of the originator whose document that you want to upload.
file
requiredstring
A file to upload.

Format: binary
purpose
requiredstring
Specifies the purpose of the uploaded file.
"DUE_DILIGENCE" - The transfer due diligence document of the originator. The size of the document should be less than 20MB. Supported file extension: .pdf, .docx, .doc.

Possible values: DUE_DILIGENCE
Select Language
1const url = 'https://sandbox.plaid.com/transfer/diligence/document/upload';
2const filePath = '/path/to/file.pdf';
3const purpose = 'DUE_DILIGENCE';
4
5const formData = new FormData();
6formData.append('file', fs.createReadStream(filePath));
7formData.append('purpose', purpose);
8formData.append('originator_client_id', originatorClientId);
9
10const headers = {
11  'PLAID-CLIENT-ID': YourClientId,
12  'PLAID-SECRET': YourSecret,
13  ...formData.getHeaders(),
14};
15
16try {
17  const response = await axios.post(url, formData, { headers });
18} catch (error) {
19  // handle error
20}
transfer/diligence/document/upload

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "4zlKapIkTm8p5KM"
3}
Was this helpful?

Webhooks

TRANSFER_EVENTS_UPDATE

Fired when new transfer events are available. Receiving this webhook indicates you should fetch the new events from /transfer/event/sync.

webhook_type
string
TRANSFER
webhook_code
string
TRANSFER_EVENTS_UPDATE
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "TRANSFER",
3  "webhook_code": "TRANSFER_EVENTS_UPDATE",
4  "environment": "production"
5}
Was this helpful?

RECURRING_NEW_TRANSFER

Fired when a new transfer of a recurring transfer is originated.

webhook_type
string
TRANSFER
webhook_code
string
RECURRING_NEW_TRANSFER
recurring_transfer_id
string
Plaid’s unique identifier for a recurring transfer.
transfer_id
string
Plaid’s unique identifier for a transfer.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "TRANSFER",
3  "webhook_code": "RECURRING_NEW_TRANSFER",
4  "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
5  "transfer_id": "271ef220-dbf8-caeb-a7dc-a2b3e8a80963",
6  "environment": "production"
7}
Was this helpful?

RECURRING_TRANSFER_SKIPPED

Fired when Plaid is unable to originate a new ACH transaction of the recurring transfer on the planned date.

webhook_type
string
TRANSFER
webhook_code
string
RECURRING_TRANSFER_SKIPPED
recurring_transfer_id
string
Plaid’s unique identifier for a recurring transfer.
authorization_decision
string
A decision regarding the proposed transfer.
approved – The proposed transfer has received the end user's consent and has been approved for processing by Plaid. The decision_rationale field is set if Plaid was unable to fetch the account information. You may proceed with the transfer, but further review is recommended (i.e., use Link in update to re-authenticate your user when decision_rationale.code is ITEM_LOGIN_REQUIRED). Refer to the code field in the decision_rationale object for details.
declined – Plaid reviewed the proposed transfer and declined processing. Refer to the code field in the decision_rationale object for details.

Possible values: approved, declined
authorization_decision_rationale_code
string
A code representing the rationale for approving or declining the proposed transfer. Possible values are:
MANUALLY_VERIFIED_ITEM – Item created via same-day micro deposits, limited information available. Plaid will offer approved as a transaction decision.
ITEM_LOGIN_REQUIRED – Unable to collect the account information due to Item staleness. Can be rectified using Link in update mode. Plaid will offer approved as a transaction decision.
PAYMENT_PROFILE_LOGIN_REQUIRED - Unable to collect the account information due to invalid login when using Payment Profiles. Can be rectified using update mode for Payment Profile. Plaid will offer approved as a transaction decision.
ERROR – Unable to collect the account information due to an error. Plaid will offer approved as a transaction decision.
NSF – Transaction likely to result in a return due to insufficient funds. Plaid will offer declined as a transaction decision.
RISK - Transaction is high-risk. Plaid will offer declined as a transaction decision.
TRANSFER_LIMIT_REACHED - One or several transfer limits are reached, e.g. monthly transfer limit. Plaid will offer declined as a transaction decision.
MIGRATED_ACCOUNT_ITEM - Item created via /transfer/account_migration endpoint, limited information available. Plaid will offer approved as a transaction decision.

Possible values: NSF, RISK, TRANSFER_LIMIT_REACHED, MANUALLY_VERIFIED_ITEM, ITEM_LOGIN_REQUIRED, PAYMENT_PROFILE_LOGIN_REQUIRED, ERROR, MIGRATED_ACCOUNT_ITEM
skipped_origination_date
string
The planned date on which Plaid is unable to originate a new ACH transaction of the recurring transfer. This will be of the form YYYY-MM-DD.

Format: date
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "TRANSFER",
3  "webhook_code": "RECURRING_TRANSFER_SKIPPED",
4  "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
5  "authorization_decision": "declined",
6  "authorization_decision_rationale_code": "NSF",
7  "skipped_origination_date": "2022-11-30",
8  "environment": "production"
9}
Was this helpful?

RECURRING_CANCELLED

Fired when a recurring transfer is cancelled by Plaid.

webhook_type
string
TRANSFER
webhook_code
string
RECURRING_CANCELLED
recurring_transfer_id
string
Plaid’s unique identifier for a recurring transfer.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "TRANSFER",
3  "webhook_code": "RECURRING_CANCELLED",
4  "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
5  "environment": "production"
6}
Was this helpful?

api partner

Partner endpoints and webhooks

Create and manage end customers

Reseller Partner Endpoints and Webhooks

These endpoints and webhooks are used by Plaid reseller partners to create and manage their end customers.

Endpoints
/partner/customer/createCreate an end customer
/partner/customer/getGet the status of an end customer
/partner/customer/oauth_institutions/getGet the OAuth-institution registration status for an end customer
/partner/customer/enableEnable an end customer in Production
/partner/customer/removeRemove an end customer
Webhooks
PARTNER_END_CUSTOMER_OAUTH_STATUS_UPDATEDCustomer OAuth status updated

Endpoints

/partner/customer/create

Creates a new end customer for a Plaid reseller.

The /partner/customer/create endpoint is used by reseller partners to create end customers.

partner/customer/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
company_name
requiredstring
The company name of the end customer being created. This will be used to display the end customer in the Plaid Dashboard. It will not be shown to end users.
is_diligence_attested
requiredboolean
Denotes whether or not the partner has completed attestation of diligence for the end customer to be created.
products
required[string]
The products to be enabled for the end customer.

Possible values: assets, auth, balance, identity, income_verification, investments, liabilities, transactions, employment
create_link_customization
boolean
If true, the end customer's default Link customization will be set to match the partner's. You can always change the end customer's Link customization in the Plaid Dashboard. See the Link Customization docs for more information.
logo
string
Base64-encoded representation of the end customer's logo. Must be a PNG of size 1024x1024 under 4MB. The logo will be shared with financial institutions and shown to the end user during Link flows. A logo is required if create_link_customization is true. If create_link_customization is false and the logo is omitted, a stock logo will be used.
legal_entity_name
requiredstring
The end customer's legal name. This will be shared with financial institutions as part of the OAuth registration process. It will not be shown to end users.
website
requiredstring
The end customer's website.
application_name
requiredstring
The name of the end customer's application. This will be shown to end users when they go through the Plaid Link flow.
technical_contact
object
The technical contact for the end customer. Defaults to partner's technical contact if omitted.
email
string
billing_contact
object
The billing contact for the end customer. Defaults to partner's billing contact if omitted.
email
string
customer_support_info
object
This information is public. Users of your app will see this information when managing connections between your app and their bank accounts in Plaid Portal. Defaults to partner's customer support info if omitted.
address
requiredobject
The end customer's address.
city
string
street
string
region
string
country_code
string
ISO-3166-1 alpha-2 country code standard.
is_bank_addendum_completed
requiredboolean
Denotes whether the partner has forwarded the Plaid bank addendum to the end customer.
assets_under_management
object
Assets under management for the given end customer. Required for end customers with monthly service commitments.
amount
requirednumber
iso_currency_code
requiredstring
redirect_uris
[string]
A list of URIs indicating the destination(s) where a user can be forwarded after completing the Link flow; used to support OAuth authentication flows when launching Link in the browser or via a webview. URIs should not contain any query parameters. When used in Production or Development, URIs must use https. To specify any subdomain, use * as a wildcard character, e.g. https://*.example.com/oauth.html. To modify redirect URIs for an end customer after creating them, go to the end customer's API page in the Dashboard.
Select Language
1const request: PartnerCustomerCreateRequest = {
2      address: {
3          city: city,
4          country_code: countryCode,
5          postal_code: postalCode,
6          region: region,
7          street: street
8      },
9      application_name: applicationName,
10      billing_contact: {
11          email: billingEmail,
12          given_name: billingGivenName,
13          family_name: billingFamilyName
14      },
15      customer_support_info: {
16          email: supportEmail,
17          phone_number: supportPhoneNumber,
18          contact_url: supportContactUrl,
19          link_update_url: linkUpdateUrl
20      },
21      company_name: companyName,
22      is_bank_addendum_completed: true,
23      is_diligence_attested: true,
24      legal_entity_name: legalEntityName,
25      products: products,
26      technical_contact: {
27          email: technicalEmail,
28          given_name: technicalGivenName,
29          family_name: technicalFamilyName
30      },
31      website: website
32};
33try {
34  const response = await plaidClient.partnerCustomerCreate(request);
35  const endCustomer = response.data.end_customer;
36} catch (error) {
37  // handle error
38}
partner/customer/create

Response fields and example

end_customer
object
The details for an end customer.
client_id
string
status
string
The status of the given end customer.
UNDER_REVIEW: The end customer has been created and enabled in the non-Production environments. The end customer must be manually reviewed by the Plaid team before it can be enabled in production, at which point its status will automatically transition to PENDING_ENABLEMENT or DENIED.
PENDING_ENABLEMENT: The end customer is ready to be enabled in the Production environment. Call the /partner/customer/enable endpoint to enable the end customer in Production.
ACTIVE: The end customer has been enabled in all environments.
DENIED: The end customer has been created and enabled in the non-Production environments, but it did not pass review by the Plaid team and therefore cannot be enabled in the Production environment. Talk to your Account Manager for more information.

Possible values: UNDER_REVIEW, PENDING_ENABLEMENT, ACTIVE, DENIED
secrets
object
The secrets for the newly created end customer in non-Production environments.
sandbox
string
The end customer's secret key for the Sandbox environment.
development
string
The end customer's secret key for the Development environment.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "end_customer": {
3    "client_id": "7f57eb3d2a9j6480121fx361",
4    "company_name": "Plaid",
5    "status": "ACTIVE",
6    "secrets": {
7      "sandbox": "b60b5201d006ca5a7081d27c824d77",
8      "development": "95e56a510204f293d3bebd4b9cf5c7"
9    }
10  },
11  "request_id": "4zlKapIkTm8p5KM"
12}
Was this helpful?

/partner/customer/get

Returns a Plaid reseller's end customer.

The /partner/customer/get endpoint is used by reseller partners to retrieve data about a single end customer.

partner/customer/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
Select Language
1const request: PartnerCustomerGetRequest = {
2  end_customer_client_id: clientId,
3};
4try {
5  const response = await plaidClient.partnerCustomerGet(request);
6  const endCustomer = response.data.end_customer;
7} catch (error) {
8  // handle error
9}
partner/customer/get

Response fields and example

end_customer
object
The details for an end customer.
client_id
string
status
string
The status of the given end customer.
UNDER_REVIEW: The end customer has been created and enabled in the non-Production environments. The end customer must be manually reviewed by the Plaid team before it can be enabled in production, at which point its status will automatically transition to PENDING_ENABLEMENT or DENIED.
PENDING_ENABLEMENT: The end customer is ready to be enabled in the Production environment. Call the /partner/customer/enable endpoint to enable the end customer in Production.
ACTIVE: The end customer has been enabled in all environments.
DENIED: The end customer has been created and enabled in the non-Production environments, but it did not pass review by the Plaid team and therefore cannot be enabled in the Production environment. Talk to your Account Manager for more information.

Possible values: UNDER_REVIEW, PENDING_ENABLEMENT, ACTIVE, DENIED
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "end_customer": {
3    "client_id": "7f57eb3d2a9j6480121fx361",
4    "company_name": "Plaid",
5    "status": "ACTIVE"
6  },
7  "request_id": "4zlKapIkTm8p5KM"
8}
Was this helpful?

/partner/customer/oauth_institutions/get

Returns OAuth-institution registration information for a given end customer.

The /partner/customer/oauth_institutions/get endpoint is used by reseller partners to retrieve OAuth-institution registration information about a single end customer. To learn how to set up a webhook to listen to status update events, visit the reseller documentation.

partner/customer/oauth_institutions/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
Select Language
1const request: PartnerCustomerOAuthInstitutionsGetRequest = {
2  end_customer_client_id: clientId,
3};
4try {
5  const response = await plaidClient.partnerCustomerOAuthInstitutionsGet(request);
6} catch (error) {
7  // handle error
8}
partner/customer/oauth_institutions/get

Response fields and example

flowdown_status
string
The status of the addendum to the Plaid MSA ("flowdown") for the end customer.

Possible values: NOT_STARTED, IN_REVIEW, NEGOTIATION, COMPLETE
questionnaire_status
string
The status of the end customer's security questionnaire.

Possible values: NOT_STARTED, RECEIVED, COMPLETE
institutions
[object]
The OAuth institutions with which the end customer's application is being registered.
name
string
environments
object
Registration statuses by environment.
development
string
The registration status for the end customer's application.

Possible values: NOT_STARTED, PROCESSING, APPROVED, ENABLED, ATTENTION_REQUIRED
production
string
The registration status for the end customer's application.

Possible values: NOT_STARTED, PROCESSING, APPROVED, ENABLED, ATTENTION_REQUIRED
production_enablement_date
nullablestring
The date on which the end customer's application was approved by the institution, or an empty string if their application has not yet been approved.
classic_disablement_date
nullablestring
The date on which non-OAuth Item adds will no longer be supported for this institution, or an empty string if no such date has been set by the institution.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "flowdown_status": "COMPLETE",
3  "questionnaire_status": "COMPLETE",
4  "institutions": [
5    {
6      "name": "Chase",
7      "institution_id": "ins_56",
8      "environments": {
9        "production": "PROCESSING",
10        "development": "PROCESSING"
11      },
12      "production_enablement_date": null,
13      "classic_disablement_date": "2022-06-30"
14    },
15    {
16      "name": "Capital One",
17      "institution_id": "ins_128026",
18      "environments": {
19        "production": "ENABLED",
20        "development": "ENABLED"
21      },
22      "production_enablement_date": "2022-12-19",
23      "classic_disablement_date": null
24    }
25  ],
26  "request_id": "4zlKapIkTm8p5KM"
27}
Was this helpful?

/partner/customer/enable

Enables a Plaid reseller's end customer in the Production environment.

The /partner/customer/enable endpoint is used by reseller partners to enable an end customer in the Production environment.

partner/customer/enable

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
Select Language
1const request: PartnerCustomerEnableRequest = {
2  end_customer_client_id: clientId,
3};
4try {
5  const response = await plaidClient.partnerCustomerEnable(request);
6  const productionSecret = response.data.production_secret;
7} catch (error) {
8  // handle error
9}
partner/customer/enable

Response fields and example

production_secret
string
The end customer's secret key for the Production environment.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "production_secret": "79g03eoofwl8240v776r2h667442119",
3  "request_id": "4zlKapIkTm8p5KM"
4}
Was this helpful?

/partner/customer/remove

Removes a Plaid reseller's end customer.

The /partner/customer/remove endpoint is used by reseller partners to remove an end customer. Removing an end customer will remove it from view in the Plaid Dashboard and deactivate its API keys. This endpoint can only be used to remove an end customer that has not yet been enabled in Production.

partner/customer/remove

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
Select Language
1const request: PartnerCustomerRemoveRequest = {
2  end_customer_client_id: clientId,
3};
4try {
5  const response = await plaidClient.partnerCustomerRemove(request);
6} catch (error) {
7  // handle error
8}
partner/customer/remove

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "4zlKapIkTm8p5KM"
3}
Was this helpful?

Webhooks

PARTNER_END_CUSTOMER_OAUTH_STATUS_UPDATED

The webhook of type PARTNER and code END_CUSTOMER_OAUTH_STATUS_UPDATED will be fired when a partner's end customer has an update on their OAuth registration status with an institution.

webhook_type
string
PARTNER
webhook_code
string
END_CUSTOMER_OAUTH_STATUS_UPDATED
end_customer_client_id
string
The client ID of the end customer
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
institution_id
string
The institution ID
institution_name
string
The institution name
status
string
The OAuth status of the update

Possible values: not-started, processing, approved, enabled, attention-required
1{
2  "webhook_type": "PARTNER",
3  "webhook_code": "END_CUSTOMER_OAUTH_STATUS_UPDATED",
4  "end_customer_client_id": "634758733ebb4f00134b85ea",
5  "environment": "production",
6  "institution_id": "ins_127989",
7  "institution_name": "Bank of America",
8  "status": "attention-required"
9}
Was this helpful?

transactions sync migration

Transactions Sync migration guide

Learn how to migrate from the /transactions/get endpoint to the /transactions/sync endpoint

Overview

/transactions/sync is a newer endpoint that replaces /transactions/get and provides a simpler and easier model for managing transactions updates. While /transactions/get provides all transactions within a date range, /transactions/sync instead uses a cursor to provide all new, modified, and removed transactions that occurred since your previous request. With this cursor-based pagination, you do not need to worry about making redundant API calls to avoid missing transactions. Updates returned by /transactions/sync can be patched into your database, allowing you to avoid a complex transaction reconciliation process or having to keep track of which updates have already been applied.

This guide outlines how to update your existing /transactions/get integration to use the /transactions/sync endpoint and simplify your Plaid integration.

Looking for an example in code? Check out Pattern on GitHub for a complete, best-practice implementation of the Transactions Sync API within a sample app.

Update your client library

If you are using client libraries, you may need to update your current library to use /transactions/sync. The following are the minimum Plaid client library versions required to support /transactions/sync for each language:

  • Python: 9.4.0
  • Node: 10.4.0
  • Ruby: 15.5.0
  • Java: 11.3.0
  • Go: 3.4.0

Detailed upgrade notes are language-specific may be found in the README and Changelog of the specific library. See the library's repo on the Plaid GitHub for more information.

Update callsites and pagination logic

Replace all instances of /transactions/get with /transactions/sync. /transactions/sync has a slightly different call signature from /transactions/get and does not have the count parameter inside the options object and uses a cursor instead of a start_date and end_date. Pagination logic is also different and relies on the has_more flag instead of the transactions_count value. Note that when requesting paginated updates with /transactions/sync, unlike when using /transactions/get, it is important to retrieve all available updates before persisting the transactions updates to your database.

For copy-and-pastable examples of how to call /transactions/sync, including complete pagination logic, see the API reference code samples for /transactions/sync.

If a call to /transactions/sync fails when retrieving a paginated update as a result of the TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION error, the entire pagination request loop must be restarted beginning with the cursor for the first page of the update, rather than retrying only the single request that failed.

Update callsites for account and Item data

Unlike /transactions/get, /transactions/sync does not return an account object or Item object. If your app relies on getting account data, such as balance, from the /transactions/get call, use /accounts/get instead to retrieve this information. If it relies on Item data, such as Item health status, use /item/get.

Update webhook handlers

When using /transactions/sync, you should not listen for the webhooks HISTORICAL_UPDATE, DEFAULT_UPDATE, INITIAL_UPDATE, or TRANSACTIONS_REMOVED. While these webhooks will still be sent in order to maintain backwards compatibility, they are not required for the business logic used by /transactions/sync.

Instead, update your webhook handlers to listen for the SYNC_UPDATES_AVAILABLE webhook and to call /transactions/sync when this webhook is received.

Update initial call trigger

Unlike the /transactions/get webhooks, the SYNC_UPDATES_AVAILABLE webhook will not be fired for an Item unless /transactions/sync has been called at least once for that Item. For this reason, you must call /transactions/sync at least once before any sync webhook is received. After that point, rely on the SYNC_UPDATES_AVAILABLE webhook.

Unlike /transactions/get, /transactions/sync will not return the PRODUCT_NOT_READY error if transactions data is not yet ready when /transactions/sync is first called. Instead, you will receive a response with no transactions and a null cursor. Even if no transactions data is available, this call will still initialize the SYNC_UPDATES_AVAILABLE webhook, and it will fire once data becomes available.

The first call to /transactions/sync once historical updates are available will often have substantially higher latency (up to 8x) than the equivalent call in a /transactions/get-based implementation. Depending on your application's logic, you may need to adjust user-facing messaging or hard-coded timeout settings.

Update transaction reconciliation logic

The response to /transactions/sync includes the patches you will need to apply in the added, removed, and modified arrays within its response. You should apply these to your transactions records. Any additional logic required to fetch or reconcile transactions data can be removed.

Migrating existing Items

You likely already have transactions stored for existing Items. If you onboard an existing Item onto /transactions/sync with "cursor": "" in the request body, the endpoint will return all historical transactions data associated with that Item up until the time of the API call (as "adds"). You may reconcile these with your stored copy of transactions to ensure that it reflects the the Item's true state.

If you have a large number of Items to update, this reconciliation process may be slow and generate excessive system load. One other option for onboarding existing Items onto /transactions/sync is using "cursor": "now" in the request body. The endpoint will return a response containing no transaction updates, but only a cursor that will allow you to retrieve all transactions updates associated with that Item going forward, after the time of the API call. Accordingly, you should ensure that your local copy of transactions for an Item is up-to-date at the time you call /transactions/sync with "cursor": "now" for it, or else any transaction updates that occurred between the time that you last pulled fresh data and the time of your /transactions/sync call may be missing.

"cursor": "now" will work exactly like a cursor that was found by starting with "cursor": "" and paginating through all updates, with the only difference being that a transaction created before, but modified after, those requests would be returned as "added" if using "cursor": "now", and "modified" if using "cursor": "".

If you ever want to completely rebuild your local copy of transactions for an Item previously onboarded with "cursor": "now", you may still do so with "cursor": "".

Note that we strongly recommend that this cursor only be used with Items for which you've already used with /transactions/get, and not any new Items, which should always be onboarded with "cursor": "".

Test your integration

You can perform basic testing of your integration's business logic in Sandbox, using the /sandbox/item/fire_webhook endpoint to simulate SYNC_UPDATES_AVAILABLE. If this testing succeeds, you should then test your integration with internal test accounts in Development or Production before releasing it to your full Production userbase.

Example code

For a full working example of a Plaid-powered app using /transactions/sync, see Plaid Pattern.

link initializing products

Choosing when to initialize products

Increase conversion and reduce costs by learning how to configure the Link products array

Overview

When you create a link_token, you specify which products to initialize Link with via the products field in /link/token/create. This choice impacts which products you will be billed for, the latency of Link initialization, and which institutions your user can connect to. You can choose whether initialize Link with all of your products or to defer initializing some of those products until later. You can also use the Required if Suppported Products feature to conditionally initialize certain products.

In general, it is recommended to initialize Link with the minimal set of products you need.

Initializing products post-Link

If an Item was not initialized with a given product at the time of Link, making a product endpoint call for information about that Item will automatically initialize the Item with that product. For example, if an Item was not initialized with Transactions during Link, calling /transactions/sync or /transactions/get on that Item for the first time will initialize it with the Transactions product.

Some exceptions exist: Identity Verification and Payment Initiation cannot be initialized post-Link. If you are using Data Transparency Messaging Beta, you cannot initialize products post-link unless you configure them via additional_consented_products.

Impacts of initialization timing on billing

If you initialize Link with a product that is billed under an initialization or subscription model, you will be billed when an Item for the product is created, even if you are not yet using the product’s endpoints.

To avoid unwanted charges, do not initialize Link with a product in Production unless you are sure you are going to use that product. To learn more about how Plaid bills each product, see Billing.

Impacts of initialization timing on conversion

The products Link is initialized with will determine which institutions and accounts are available in Link. If Link is initialized with multiple products, only institutions supporting all of those products will be available. If the user selects a filtered institution in the Link UI, a "Connectivity not supported" error will appear. In addition, if the user does not have at least one account that is supported by each selected product, products a NO_AUTH_ACCOUNTS or NO_ACCOUNTS error will occur. See the accounts / product support matrix for further details.

To avoid overly filtering the institution and account list, you can use Required if Supported Products, or initialize Link with your required products and call other products’ endpoints later.

Impacts of initialization timing on latency

Some Plaid products that fetch an extended amount of history, such as Transactions, Investments, and Signal, may require up to a minute or more to fetch all the data that they need the first time that they are initialized for a specific Item. For these products, Plaid begins to prepare data upon Item link if the Item was initialized with the product. If the Item was not initialized with the product during Link, Plaid will only begin to fetch data for that product the first time you call an endpoint belonging to that product, such as /transactions/sync or /signal/prepare.

Required if Supported Products

In order to require a secondary product when possible, without excluding users who don't have access to that product from linking their account, you can specify the secondary product in the required_if_supported_products array when calling /link/token/create. (It is possible to specify multiple products in this field as well, as long as at least one always-required product is specified in the regular products array.)

When a product is listed in required_if_supported_products, Plaid will require that product if possible. If the institution the end user is attempting to link supports the secondary product, and the user grants Plaid access to an account at the institution that is compatible with it, Plaid will treat the product as though it was listed in the products array. If the institution does not support the product, if the user doesn't have accounts compatible with it, or if the user has compatible accounts but doesn't grant access to them, Plaid will treat the product as though it had not been specified in the /link/token/create call. (To determine whether a product was successfully added to the Item, you can call /item/get after obtaining your access_token and look at the value of the products array.)

For example, if you call /link/token/create with both Auth and Identity in the products array, a user can only link an account if both Auth and Identity are supported by their institution, and they cannot use flows like Same-day Micro-deposits. However, if you list Auth in products and Identity in required_if_supported_products, users will be able to link checking and savings accounts at any institution that supports Auth, even if the institution does not support Identity. They will also be able to access flows that require Auth to be initialized by itself, like Same-day Micro-deposits. If the institution does support both Auth and Identity, Plaid will attempt to initialize the Item with both products. If the institution has an OAuth flow where Identity access can be configured as a separate permission, and the user does not grant access to Identity, the Link attempt will not complete and the user will be prompted to re-try the Link flow.

As another example, if Transactions and Auth are both listed as products, users will only be able to link checking or savings accounts, since a filter is automatically applied whenever Auth is in the products array that limits acceptable accounts to checking and savings accounts. If Transactions is listed in products and Auth is listed in required_if_supported_products, users will be able to link other Transactions-compatible account types, such as credit cards or money market accounts, but if they do link a checking or savings account, Plaid will fetch Auth data for that account.

When to use Required if Supported Products

If your only reason for initializing Link without a specific product is to increase the number of institutions covered, it is recommended to use the required_if_supported_products field rather than initializing the other product later. Initializing both products during the initial Link will make it easier to obtain all of the consent that is required at institutions that use OAuth, since the user will be prompted to fix their selections during the OAuth flow if they do not grant the required consent for all products. Initializing both products upfront can also reduce latency, since it allows Plaid to begin fetching data immediately and to optimize the order in which different types of data are requested.

If, on the other hand, you are not initializing with a product upfront because you don't yet know during Link initialization whether you'll need the product, you should not use required_if_supported_products and should initialize with the product post-Link. For example, if your app primarily uses Auth for funds transfers but also offers an optional budgeting add-on that uses Transactions, you should initialize by calling /transactions/sync only once your user opts in to using the budgeting tool. This will prevent you from being billed for a product before you are sure you need to use it. It will also maximize your Item add success rates, since if Plaid encounters an error extracting data for a Required if Supported Product during Link, the Item add will not complete.

Not all products can be listed in the required_if_supported_products field. For more details, see the API Reference.

Initializing Link when using Data Transparency Messaging

If you have opted in to the Data Transparency Messaging Beta, then depending on the permissions that were granted during the original Link flow, you may not be able to initialize an Item with an additional product post-Link simply by calling a product endpoint, as you will need to have obtained the proper consent for that product.

Instead, you should specify this product in the additional_consented_products array when first calling /link/token/create. If the Item has already been created and the product you need is not in the Item's consented_products field (which can be checked by calling /item/get), you need to obtain additional user consent, which you can do by sending the user through update mode with the products array updated to include the full set of products you would like to obtain consent for.

Both the additional_consented_products array and update mode methods obtain consent for a product without initializing the Item for that product, avoiding any billing or performance implications.

Special cases for Link initialization

There are some exceptions to the ability to initialize products by calling their endpoints:

  • Bank Income and Assets can both be initialized post-Link, but may require re-launching Link to obtain additional consent. See Verifying Bank Income for existing Items and Adding Assets to existing Items.
  • Identity Verification and Payment Initiation cannot be initialized post-Link.
  • When Auth is initialized post-Link, the main Instant Auth flow can be used, but the less common Instant Match, Automated Micro-deposits, or Same Day Micro-deposits flows cannot be initialized post-Link, as these are interactive flows that require user input.

Some products cannot be initialized alongside other products in the same Link session:

  • To use Same Day Micro-deposits, Auth must be the only product Link is initialized with.
  • Income can only be initialized alongside other products if using Bank Income; Payroll Income and Document Income cannot be initialized alongside other products.
  • Identity Verification and Payment Initiation cannot be initialized alongside any other products. If you need to use these products along with other Plaid products, your user will need to launch the Link flow a second time.

Recommendations for initializing Link with specific product combinations

The recommendations below assume that you know upfront that you will want to use all of the products listed.

Auth and Identity

Only initialize with both Auth and Identity if identity data is critical to your fraud detection model. Otherwise, initialize with Auth in the products array, then include Identity as a required_if_supported_product. Initializing with Auth by itself gives access to a slightly larger range of institutions than initializing with Auth and Identity together. Initializing with Auth alone also allows you to take advantage of Same Day Micro-deposit verification, which can increase conversion and which can only be used if Auth is the only product in the products array.

Auth and Signal

If your integration uses the Same-Day Micro-deposits flow, then to maximize conversion, initialize with Auth, then call /signal/prepare. Otherwise, you can initialize with both Auth and Signal and do not need to call /signal/prepare.

Auth, Signal, and Identity

Initialize with Auth, and list Identity in the required_if_supported_products field. Then call /signal/prepare. Initializing without Identity as a required product will maximize Link conversion, as described under the Auth and Identity section, and initializing Identity before calling /signal/prepare will minimize latency.

Auth and Assets

Initialize with Assets, and list Auth in the required_if_supported_products field. If Auth ends up not being a supported product, send the user through Link again in order to initialize a separate Item with Auth. This increases the number of institutions available and also allows you to take advantage of Same Day Micro-deposit verification, which can increase conversion.

Liabilities and Transactions

If you want to get both loan data (such as APRs, balance due, and repayment history) and transaction history from the same account, initialize with whichever product is more important for your use case (Transactions if transaction history is more important, Liabilities if loan data is more important). Then list the other product in the required_if_supported_products field.

Bank Income and Transactions

Initialize with Bank Income first, then call Transactions endpoints later. If an Item is initialized with Transactions during Link, you will not be able to start the Bank Income flow until the Transactions data pull has completed, which may take up to several minutes.

Investments and Transactions

Initialize with Transactions, then specify Investments in the required_if_supported_products array. This will optimize institution coverage while reducing the latency involved in fetching history for both products. Note that the overwhelming majority of institutions that support Investments also support Transactions.

Income and Assets

If using Payroll Income or Document Income, initialize Link with Income Verification first to have your user verify their income, then launch Link again initialized with the Assets product, as Payroll Income and Document Income cannot be used with any other products. (Note that the order of these steps does not matter -- you can launch Link with Assets and then launch it again with Income Verification.)

If using Bank Income, initialize with Assets. Then, see the instructions on Verifying Bank Income for existing Items to add Bank Income to the Item. Or, you can initialize with Bank Income first and then see the instructions on Getting an Asset Report for an existing Item to add Assets.

link ios ios v2 migration

1.x to 2.x Migration Guide

Reference for migrating the Link iOS SDK from 1.x to 2.x

Summary of changes

Plaid released version 2.0.0 of the SDK on September 24th, 2020. Upgrading to the new 2.x SDK allows you to take advantage of a unified mobile API and support all new features, such as link-token based Payment Initiation. This guide describes how to upgrade a Plaid iOS integration from the 1.x SDK to the 2.x SDK.

Remove the custom "Prepare for distribution" Build Phase

LinkKit 2.x is now an XCFramework bundle type, which no longer requires the custom Build Phase to strip the iOS Simulator part from the framework.

Remove setup

Remove any of the preflight setup methods listed below that your application may make use of. They are no longer part of the API and need to be removed.

Select Language
1// Setup using shared configuration,
2PLKPlaidLink.setup { (success, error) in /* … */ }
3
4// using shared configuration and item-add token
5PLKPlaidLink.setupWithSharedConfiguration(usingItemAddToken:itemAddToken) { (success, error) in /* … */ }
6
7// using custom configuration,
8PLKPlaidLink.setup(with: linkConfiguration) { (success, error) in /* … */ }
9
10// using custom configuration and item-add token,
11PLKPlaidLink.setupWithConfiguration(with: linkConfiguration, itemAddToken: itemAddToken)
12    { (success, error) in /* … */ }
13
14// using public-token and shared configuration
15PLKPlaidLink.setup(withPublicToken:publicToken) { (success, error) in /* … */ }
16
17// using public-token and custom configuration
18PLKPlaidLink.setup(withPublicToken:publicToken, configuration:linkConfiguration) { (success, error) in /* … */ }
19
20// using public-token, item-add token, and shared configuration
21PLKPlaidLink.setup(withPublicToken:publicToken, itemAddToken:itemAddToken) { (success, error) in /* … */ }
22
23// using public-token, item-add token, and custom configuration
24PLKPlaidLink.setup(withPublicToken:publicToken, itemAddToken:itemAddToken, configuration:linkConfiguration)
25    { (success, error) in /* … */ }
26
27// using public-token, link-token, and shared configuration
28PLKPlaidLink.setup(withPublicToken:publicToken, linkToken:linkToken) { (success, error) in /* … */ }
29
30// using public-token, link-token, and custom configuration
31PLKPlaidLink.setup(withPublicToken:publicToken, linkToken:linkToken, configuration:linkConfiguration)
32    { (success, error) in /* … */ }

Create a configuration

The recommended way to create a configuration for Link is to use LinkTokenConfiguration, which replaces PLKConfiguration. If you still rely on public key based configurations, we recommend you migrate your application to use Link tokens as soon as possible, and use LinkPublicKeyConfiguration until then.

Select Language
1// For recommended Link Token based configuration use:
2let linkTokenConfiguration = LinkTokenConfiguration(token: linkToken)
3    { success in /* … */ }
4
5// To continue using public key based configuration for the interim use:
6let linkPublicKeyConfiguration = LinkPublicKeyConfiguration(
7            clientName: "Link Demo",
8            environment: .sandbox,
9            products: [.transactions, .auth],
10            language: "en"
11            token: .publicKey("<#YOUR_PUBLIC_KEY#>"),
12            countryCodes: ["US"]) { (success) in /* … */ }

Notice that the PLKPlaidLinkViewDelegate has been replaced by the required onSuccess closure on LinkTokenConfiguration and LinkPublicKeyConfiguration and the optional onExit and onEvent closures.

Handler

A Handler is a one-time use object used to open a Link session. Create it as early as possible in your application lifecycle or account linking setup. If delayed until just before opening Link it can have a perceptible impact on Link startup time.

Select Language
1switch Plaid.create(linkTokenConfiguration) {
2  case .failure(let error):
3    print("Unable to create Plaid Handler due to: \(error)")
4  case .success(let handler)
5    // Store the handler for later use and call open on it when Link should start
6    self.handler = handler
7}

Open Link

Since Handler is not a UIViewController and replaces the PLKPlaidLinkViewController, it is not possible to present it directly. Remove any calls to present Link:

Select Language
1present(linkViewController, animated: true)

Instead call open on the Handler you created, specifying your preferred method of presentation:

Select Language
1// Let the handler present Link using one of the application's view controllers.
2handler.open(presentUsing: .viewController(self))
3
4// or present Link yourself in a custom manner using a closure.
5handler.open(presentUsing: .custom({ (linkViewController) in /* … */ }))

Handling results

The PLKPlaidLinkViewDelegate methods have been replaced with closures passed to either LinkTokenConfiguration or LinkPublicKeyConfiguration. While OnExitHandler and OnEventHandler are optional, the OnSuccessHandler must be provided.

1.x PLKPlaidLinkViewDelegate method2.x Handler
linkViewController:didSucceedWithPublicToken:metadata:OnSuccessHandler
linkViewController:didExitWithError:metadata:OnExitHandler
linkViewController:didHandleEvent:metadata:OnEventHandler

Each 2.x Handler closure receives one specific parameter, containing the two equivalent variables for the parameters that the corresponding PLKPlaidLinkViewDelegate method received.

  • OnSuccessHandler receives LinkSuccess, which contains the publicToken and metadata specific to LinkSuccess
  • OnExitHandler receives LinkExit, which contains an optional error and metadata specific to LinkExit
  • OnEventHandler receives LinkEvent, which contains the eventName and metadata specific to LinkEvent
SuccessMetadata

Link SDK 1.x returned an untyped NSDictionary and provided constants for key names, e.g. kPLKMetadataInstitutionKey. The untyped dictionary has been replaced with the SuccessMetadata type containing success metadata specific properties.

1.x metadata key constant2.x SuccessMetadata property
kPLKMetadataInstitutionKeyinstitution
kPLKMetadataInstitutionIdKeyinstitution.id
kPLKMetadataInstitutionNameKeyinstitution.name
kPLKMetadataAccountsKeyaccounts; see mapping below
kPLKMetadataLinkSessionIdKeylinkSessionID
N/AmetadataJSON
1.x account key constant2.x Account property
kPLKMetadataIdKeyid
kPLKMetadataNameKeyname
kPLKMetadataMaskKeymask
kPLKMetadataTypeKeyN/A; The account type is now encoded within the subtype
kPLKMetadataSubtypeKeysubtype
kPLKMetadataAccountVerificationStatusKeyverificationStatus
ExitMetadata

Link SDK 1.x returned a untyped NSDictionary and provided constants for key names, e.g. kPLKMetadataRequestIdKey The untyped dictionary has been replaced with the ExitMetadata type containing exit metadata specific properties.

1.x key constant2.x ExitMetadata property
kPLKMetadataErrorCodeKeyerror.errorCode; note that error code and error type are combined in a single Swift enum
kPLKMetadataErrorTypeKeysee above
kPLKMetadataErrorMessageKeyerror.errorMessage
N/Aerror.displayMessage
kPLKMetadataStatusKeyexitStatus
kPLKMetadataLinkSessionIdKeylinkSessionID
kPLKMetadataInstitutionIdKeyinstitutionID
kPLKMetadataInstitutionNameKeyinstitutionName
kPLKMetadataInstitutionSearchQueryKeyinstitutionSearchQuery
kPLKMetadataLinkSessionIdKeylinkSessionID
kPLKMetadataMFATypeKeymfaType
kPLKMetadataTimestampKeytimestamp
kPLKMetadataViewNameKeyviewName
N/AmetadataJSON
EventMetadata

Link SDK 1.x returned a untyped NSDictionary and provided constants for key names, e.g. kPLKMetadataRequestIdKey The untyped dictionary has been replaced with the ExitMetadata type containing exit metadata specific properties.

1.x key constant2.x ExitMetadata property
kPLKMetadataInstitutionKeystatus
kPLKMetadataInstitutionIdKeyinstitution.id
kPLKMetadataInstitutionNameKeyinstitution.name
kPLKMetadataLinkSessionIdKeylinkSessionID
kPLKMetadataRequestIdKeyrequestID
N/AmetadataJSON

Every metadata now includes a metadataJSON property which contains unprocessed metadata from the Plaid API.

Select Language
1let onSuccessHandler: OnSuccessHandler = { (success) in
2  // Send success.publicToken to your server and exchange it for an access token
3  // Process any metadata according to your needs, e.g. metadata.institution.name
4}
5// Pass onSuccessHandler to the onSuccess parameter of the LinkTokenConfiguration or LinkPublicKeyConfiguration initializer
Select Language
1let onExitHandler: OnExitHandler = { (exit) in
2    if let error = exit.error {
3        // Handle errors according to your app.
4        switch error.errorCode {
5        case .rateLimitExceeded(let code):
6            print("Encountered rate limit \(code)")
7        default:
8            print("Unhandled error \(error.errorCode)")
9        }
10    }
11    // Process any metadata depending on your needs, e.g. exit.metadata.institution.name
12}
13linkConfiguration.onExit = onExitHandler
Select Language
1let onEventHandler: OnEventHandler = { (event) in
2    // Handle events and metadata according to your app.
3    let metadata = event.metadata
4    switch event.eventName {
5    case .selectInstitution:
6        // Process any metadata according to your needs, e.g. metadata.institutionName
7        print("Selected institution \(metadata.institutionName ?? "") (\(metadata.institutionID ?? "")")
8    default:
9        print("Ignored event \(event)")
10    }
11}
12linkConfiguration.onEvent = onEventHandler

auth partnerships checkout

Add Checkout.com to your app

Use Checkout.com with Plaid Auth to send and receive payments!

Partnership Checkout.com logo

Overview

Plaid and Checkout.com have partnered to offer a more secure and frictionless ACH payments experience. Plaid enables the authentication of external bank accounts and returns account data that is exchanged securely to Checkout.com prior to payment initiation - businesses no longer need to hold any sensitive customer account information.

Companies can then easily process ACH payments using Checkout.com’s unified payments API. Businesses choose Checkout.com to power connected payments with its high authorization rates, global coverage, and modular microservices model. Checkout.com makes it easy for businesses to access a full suite of payment offerings, through one seamless solution.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Checkout.com account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Checkout.com processor_token, which allows you to quickly and securely verify a bank funding source via Checkout.com's API without having to store any sensitive banking information. Utilizing Plaid + Checkout.com enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Checkout.com in order to use the Plaid + Checkout.com integration. You'll also need to enable your Plaid account for the Checkout.com integration.

First, you will need to work with the Checkout.com team to sign up for a Checkout.com account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Checkout.com to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Checkout.com processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Checkout.com, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Checkout.com processor_token. You'll send this token to Checkout.com and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Checkout.com processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'checkout',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Checkout.com Production credentials prior to initiating live payment transactions in the Checkout.com API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

api sandbox

Sandbox endpoints

API reference for Sandbox endpoints

Introduction

Plaid's Sandbox environment provides a number of endpoints that can be used to configure testing scenarios. These endpoints are unique to the Sandbox environment and cannot be used in Development or Production. For more information on these endpoints, see Sandbox.

In this section
/sandbox/public_token/createBypass the Link flow for creating an Item
/sandbox/processor_token/createBypass the Link flow for creating an Item for a processor partner
/sandbox/item/reset_loginTrigger the ITEM_LOGIN_REQUIRED state for an Item
/sandbox/item/fire_webhookFire a specific webhook
/sandbox/item/set_verification_status(Auth) Set a verification status for testing micro-deposits
/sandbox/payment_profile/reset_login(Transfer) Trigger the ITEM_LOGIN_REQUIRED state for a Payment Profile
/sandbox/transfer/fire_webhook(Transfer) Fire a specific webhook
/sandbox/transfer/simulate(Transfer) Simulate a transfer event
/sandbox/transfer/sweep/simulate(Transfer) Simulate a transfer sweep event
/sandbox/transfer/test_clock/create(Transfer) Create a test clock for testing recurring transfers
/sandbox/transfer/test_clock/advance(Transfer) Advance the time on a test clock
/sandbox/transfer/test_clock/get(Transfer) Get details about a test clock
/sandbox/transfer/test_clock/list(Transfer) Get details about all test clocks
/sandbox/income/fire_webhook(Income) Fire a specific webhook

/sandbox/public_token/create

Create a test Item

Use the /sandbox/public_token/create endpoint to create a valid public_token for an arbitrary institution ID, initial products, and test credentials. The created public_token maps to a new Sandbox Item. You can then call /item/public_token/exchange to exchange the public_token for an access_token and perform all API actions. /sandbox/public_token/create can also be used with the user_custom test username to generate a test account with custom data. /sandbox/public_token/create cannot be used with OAuth institutions.

sandbox/public_token/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
institution_id
requiredstring
The ID of the institution the Item will be associated with
initial_products
required[string]
The products to initially pull for the Item. May be any products that the specified institution_id supports. This array may not be empty.

Min items: 1
Possible values: assets, auth, balance, employment, identity, income_verification, identity_verification, investments, liabilities, payment_initiation, standing_orders, transactions, transfer
options
object
An optional set of options to be used when configuring the Item. If specified, must not be null.
webhook
string
Specify a webhook to associate with the new Item.
override_username
string
Test username to use for the creation of the Sandbox Item. Default value is user_good.

Default: user_good
override_password
string
Test password to use for the creation of the Sandbox Item. Default value is pass_good.

Default: pass_good
transactions
object
An optional set of parameters corresponding to transactions options.
start_date
string
The earliest date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD.

Format: date
end_date
string
The most recent date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD.

Format: date
income_verification
object
A set of parameters for income verification options. This field is required if income_verification is included in the initial_products array.
income_source_types
[string]
The types of source income data that users will be permitted to share. Options include bank and payroll. Currently you can only specify one of these options.

Possible values: bank, payroll
bank_income
object
Specifies options for Bank Income. This field is required if income_verification is included in the initial_products array and bank is specified in income_source_types.
days_requested
integer
The number of days of data to request for the Bank Income product
user_token
string
The user token associated with the User data is being requested for.
Select group for content switcher
Select Language
1const publicTokenRequest: SandboxPublicTokenCreateRequest = {
2  institution_id: institutionID,
3  initial_products: initialProducts,
4};
5try {
6  const publicTokenResponse = await client.sandboxPublicTokenCreate(
7    publicTokenRequest,
8  );
9  const publicToken = publicTokenResponse.data.public_token;
10  // The generated public_token can now be exchanged
11  // for an access_token
12  const exchangeRequest: ItemPublicTokenExchangeRequest = {
13    public_token: publicToken,
14  };
15  const exchangeTokenResponse = await client.itemPublicTokenExchange(
16    exchangeRequest,
17  );
18  const accessToken = exchangeTokenResponse.data.access_token;
19} catch (error) {
20  // handle error
21}
sandbox/public_token/create

Response fields and example

public_token
string
A public token that can be exchanged for an access token using /item/public_token/exchange
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
3  "request_id": "Aim3b"
4}
Was this helpful?

/sandbox/processor_token/create

Create a test Item and processor token

Use the /sandbox/processor_token/create endpoint to create a valid processor_token for an arbitrary institution ID and test credentials. The created processor_token corresponds to a new Sandbox Item. You can then use this processor_token with the /processor/ API endpoints in Sandbox. You can also use /sandbox/processor_token/create with the user_custom test username to generate a test account with custom data.

sandbox/processor_token/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
institution_id
requiredstring
The ID of the institution the Item will be associated with
options
object
An optional set of options to be used when configuring the Item. If specified, must not be null.
override_username
string
Test username to use for the creation of the Sandbox Item. Default value is user_good.

Default: user_good
override_password
string
Test password to use for the creation of the Sandbox Item. Default value is pass_good.

Default: pass_good
Select group for content switcher
Select Language
1const request: SandboxProcessorTokenCreateRequest = {
2  institution_id: institutionID,
3};
4try {
5  const response = await plaidClient.sandboxProcessorTokenCreate(request);
6  const processorToken = response.data.processor_token;
7} catch (error) {
8  // handle error
9}
sandbox/processor_token/create

Response fields and example

processor_token
string
A processor token that can be used to call the /processor/ endpoints.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "processor_token": "processor-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
3  "request_id": "Aim3b"
4}
Was this helpful?

/sandbox/item/reset_login

Force a Sandbox Item into an error state

/sandbox/item/reset_login/ forces an Item into an ITEM_LOGIN_REQUIRED state in order to simulate an Item whose login is no longer valid. This makes it easy to test Link's update mode flow in the Sandbox environment. After calling /sandbox/item/reset_login, You can then use Plaid Link update mode to restore the Item to a good state. An ITEM_LOGIN_REQUIRED webhook will also be fired after a call to this endpoint, if one is associated with the Item.
In the Sandbox, Items will transition to an ITEM_LOGIN_REQUIRED error state automatically after 30 days, even if this endpoint is not called.

sandbox/item/reset_login

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
Select group for content switcher
Select Language
1const request: SandboxItemResetLoginRequest = {
2  access_token: accessToken,
3};
4try {
5  const response = await plaidClient.sandboxItemResetLogin(request);
6  // create a public_token for the Item and use it to
7  // initialize Link in update mode.
8  const pt_request: itemPublicTokenCreateRequest = {
9    access_token: accessToken,
10  };
11  const pt_response = await plaidClient.itemCreatePublicToken(pt_request);
12  const publicToken = pt_response.public_token;
13} catch (error) {
14  // handle error
15}
sandbox/item/reset_login

Response fields and example

reset_login
boolean
true if the call succeeded
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "reset_login": true,
3  "request_id": "m8MDnv9okwxFNBV"
4}
Was this helpful?

/sandbox/item/fire_webhook

Fire a test webhook

The /sandbox/item/fire_webhook endpoint is used to test that code correctly handles webhooks. This endpoint can trigger the following webhooks:
DEFAULT_UPDATE: Transactions update webhook to be fired for a given Sandbox Item. If the Item does not support Transactions, a SANDBOX_PRODUCT_NOT_ENABLED error will result.
NEW_ACCOUNTS_AVAILABLE: Webhook to be fired for a given Sandbox Item created with Account Select v2.
AUTH_DATA_UPDATE: Webhook to be fired for a given Sandbox Item created with Auth as an enabled product.
RECURRING_TRANSACTIONS_UPDATE: Recurring Transactions webhook to be fired for a given Sandbox Item. If the Item does not support Recurring Transactions, a SANDBOX_PRODUCT_NOT_ENABLED error will result.
SYNC_UPDATES_AVAILABLE: Transactions webhook to be fired for a given Sandbox Item. If the Item does not support Transactions, a SANDBOX_PRODUCT_NOT_ENABLED error will result.
PRODUCT_READY: Assets webhook to be fired when a given asset report has been successfully generated. If the Item does not support Assets, a SANDBOX_PRODUCT_NOT_ENABLED error will result.
ERROR: Assets webhook to be fired when asset report generation has failed. If the Item does not support Assets, a SANDBOX_PRODUCT_NOT_ENABLED error will result.
Note that this endpoint is provided for developer ease-of-use and is not required for testing webhooks; webhooks will also fire in Sandbox under the same conditions that they would in Production or Development.

sandbox/item/fire_webhook

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
webhook_type
string
The webhook types that can be fired by this test endpoint.

Possible values: AUTH, HOLDINGS, INVESTMENTS_TRANSACTIONS, ITEM, LIABILITIES, TRANSACTIONS, ASSETS
webhook_code
requiredstring
The webhook codes that can be fired by this test endpoint.

Possible values: DEFAULT_UPDATE, NEW_ACCOUNTS_AVAILABLE, AUTH_DATA_UPDATE, RECURRING_TRANSACTIONS_UPDATE, SYNC_UPDATES_AVAILABLE, PRODUCT_READY, ERROR
Select group for content switcher
Select Language
1// Fire a DEFAULT_UPDATE webhook for an Item
2const request: SandboxItemFireWebhookRequest = {
3  access_token: accessToken
4  webhook_code: 'DEFAULT_UPDATE'
5};
6try {
7  const response = await plaidClient.sandboxItemFireWebhook(request);
8} catch (error) {
9  // handle error
10}
sandbox/item/fire_webhook

Response fields and example

webhook_fired
boolean
Value is true if the test webhook_code was successfully fired.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "webhook_fired": true,
3  "request_id": "1vwmF5TBQwiqfwP"
4}
Was this helpful?

/sandbox/item/set_verification_status

Set verification status for Sandbox account

The /sandbox/item/set_verification_status endpoint can be used to change the verification status of an Item in in the Sandbox in order to simulate the Automated Micro-deposit flow.
Note that not all Plaid developer accounts are enabled for micro-deposit based verification by default. Your account must be enabled for this feature in order to test it in Sandbox. To enable this features or check your status, contact your account manager or submit a product access Support ticket.
For more information on testing Automated Micro-deposits in Sandbox, see Auth full coverage testing.

sandbox/item/set_verification_status

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
account_id
requiredstring
The account_id of the account whose verification status is to be modified
verification_status
requiredstring
The verification status to set the account to.

Possible values: automatically_verified, verification_expired
Select group for content switcher
Select Language
1const request: SandboxItemSetVerificationStatusRequest = {
2  access_token: accessToken,
3  account_id: accountID,
4  verification_status: 'automatically_verified',
5};
6try {
7  const response = await plaidClient.sandboxItemSetVerificationStatus(request);
8} catch (error) {
9  // handle error
10}
sandbox/item/set_verification_status

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "1vwmF5TBQwiqfwP"
3}
Was this helpful?

/sandbox/payment_profile/reset_login

Reset the login of a Payment Profile

/sandbox/payment_profile/reset_login/ forces a Payment Profile into a state where the login is no longer valid. This makes it easy to test update mode for Payment Profile in the Sandbox environment.
After calling /sandbox/payment_profile/reset_login, calls to the /transfer/authorization/create with the Payment Profile will result in a decision_rationale PAYMENT_PROFILE_LOGIN_REQUIRED. You can then use update mode for Payment Profile to restore it into a good state.
In order to invoke this endpoint, you must first create a Payment Profile and go through the Link flow.

sandbox/payment_profile/reset_login

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
payment_profile_token
requiredstring
A payment profile token associated with the Payment Profile data that is being requested.
Select Language
1// force a Payment Profile into a login required state
2const request: SandboxPaymentProfileResetLoginRequest = {
3  payment_profile_token: paymentProfileToken,
4};
5try {
6  const response = await plaidClient.sandboxPaymentProfileResetLogin(request);
7} catch (error) {
8  // handle error
9}
sandbox/payment_profile/reset_login

Response fields and example

reset_login
boolean
true if the call succeeded
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "reset_login": true,
3  "request_id": "m8MDnv9okwxFNBV"
4}
Was this helpful?

/sandbox/transfer/fire_webhook

Manually fire a Transfer webhook

Use the /sandbox/transfer/fire_webhook endpoint to manually trigger a Transfer webhook in the Sandbox environment.

sandbox/transfer/fire_webhook

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
webhook
requiredstring
The URL to which the webhook should be sent.
Select Language
1const request: SandboxTransferFireWebhookRequest = {
2  webhook: 'https://www.example.com',
3};
4try {
5  const response = await plaidClient.sandboxTransferFireWebhook(request);
6  // empty response upon success
7} catch (error) {
8  // handle error
9}
sandbox/transfer/fire_webhook

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "mdqfuVxeoza6mhu"
3}
Was this helpful?

/sandbox/transfer/simulate

Simulate a transfer event in Sandbox

Use the /sandbox/transfer/simulate endpoint to simulate a transfer event in the Sandbox environment. Note that while an event will be simulated and will appear when using endpoints such as /transfer/event/sync or /transfer/event/list, no transactions will actually take place and funds will not move between accounts, even within the Sandbox.

sandbox/transfer/simulate

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
transfer_id
requiredstring
Plaid’s unique identifier for a transfer.
test_clock_id
string
Plaid’s unique identifier for a test clock. If provided, the event to be simulated is created at the virtual_time on the provided test_clock.
event_type
requiredstring
The asynchronous event to be simulated. May be: posted, settled, failed, or returned.
An error will be returned if the event type is incompatible with the current transfer status. Compatible status --> event type transitions include:
pending --> failed
pending --> posted
posted --> returned
posted --> settled
failure_reason
object
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.
ach_return_code
string
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.
description
string
A human-readable description of the reason for the failure or reversal.
Select Language
1const request: SandboxTransferSimulateRequest = {
2  transfer_id,
3  event_type: 'posted',
4  failure_reason: failureReason,
5};
6try {
7  const response = await plaidClient.sandboxTransferSimulate(request);
8  // empty response upon success
9} catch (error) {
10  // handle error
11}
sandbox/transfer/simulate

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "mdqfuVxeoza6mhu"
3}
Was this helpful?

/sandbox/transfer/sweep/simulate

Simulate creating a sweep

Use the /sandbox/transfer/sweep/simulate endpoint to create a sweep and associated events in the Sandbox environment. Upon calling this endpoint, all posted or pending transfers with a sweep status of unswept will become swept, and all returned transfers with a sweep status of swept will become return_swept.

sandbox/transfer/sweep/simulate

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
test_clock_id
string
Plaid’s unique identifier for a test clock. If provided, the sweep to be simulated is created on the day of the virtual_time on the test_clock. If the date of virtual_time is on weekend or a federal holiday, the next available banking day is used.
Select Language
1try {
2  const response = await plaidClient.sandboxTransferSweepSimulate({});
3  const sweep = response.data.sweep;
4} catch (error) {
5  // handle error
6}
sandbox/transfer/sweep/simulate

Response fields and example

sweep
nullableobject
Describes a sweep of funds to / from the sweep account.
A sweep is associated with many sweep events (events of type swept or return_swept) which can be retrieved by invoking the /transfer/event/list endpoint with the corresponding sweep_id.
swept events occur when the transfer amount is credited or debited from your sweep account, depending on the type of the transfer. return_swept events occur when a transfer is returned and Plaid undoes the credit or debit.
The total sum of the swept and return_swept events is equal to the amount of the sweep Plaid creates and matches the amount of the entry on your sweep account ledger.
id
string
Identifier of the sweep.
funding_account_id
string
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.
created
string
The datetime when the sweep occurred, in RFC 3339 format.

Format: date-time
amount
string
Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00")
If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced.
iso_currency_code
string
The currency of the sweep, e.g. "USD".
settled
nullablestring
The date when the sweep settled, in the YYYY-MM-DD format.

Format: date
status
nullablestring
The status of a sweep transfer
"pending" - The sweep is currently pending "posted" - The sweep has been posted "settled" - The sweep has settled "returned" - The sweep has been returned "failed" - The sweep has failed

Possible values: pending, posted, settled, returned, failed, null
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "sweep": {
3    "id": "d5394a4d-0b04-4a02-9f4a-7ca5c0f52f9d",
4    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
5    "created": "2020-08-06T17:27:15Z",
6    "amount": "12.34",
7    "iso_currency_code": "USD",
8    "settled": "2020-08-07"
9  },
10  "request_id": "mdqfuVxeoza6mhu"
11}
Was this helpful?

/sandbox/transfer/test_clock/create

Create a test clock

Use the /sandbox/transfer/test_clock/create endpoint to create a test_clock in the Sandbox environment.
A test clock object represents an independent timeline and has a virtual_time field indicating the current timestamp of the timeline. Test clocks are used for testing recurring transfers in Sandbox.
A test clock can be associated with up to 5 recurring transfers.

sandbox/transfer/test_clock/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
virtual_time
string
The virtual timestamp on the test clock. If not provided, the current timestamp will be used. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time
Select Language
1const request: SandboxTransferTestClockCreateRequest = {
2  virtual_time: '2006-01-02T15:04:05Z'
3};
4try {
5  const response = await plaidClient.sandboxTransferTestClockCreate(request);
6  const test_clock = response.data.test_clock;
7} catch (error) {
8  // handle error
9}
sandbox/transfer/test_clock/create

Response fields and example

test_clock
object
Defines the test clock for a transfer.
test_clock_id
string
Plaid’s unique identifier for a test clock.
virtual_time
string
The virtual timestamp on the test clock. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "test_clock": {
3    "test_clock_id": "b33a6eda-5e97-5d64-244a-a9274110151c",
4    "virtual_time": "2006-01-02T15:04:05Z"
5  },
6  "request_id": "mdqfuVxeoza6mhu"
7}
Was this helpful?

/sandbox/transfer/test_clock/advance

Advance a test clock

Use the /sandbox/transfer/test_clock/advance endpoint to advance a test_clock in the Sandbox environment.
A test clock object represents an independent timeline and has a virtual_time field indicating the current timestamp of the timeline. A test clock can be advanced by incrementing virtual_time, but may never go back to a lower virtual_time.
If a test clock is advanced, we will simulate the changes that ought to occur during the time that elapsed. For instance, a client creates a weekly recurring transfer with a test clock set at t. When the client advances the test clock by setting virtual_time = t + 15 days, 2 new originations should be created, along with the webhook events.
The advancement of the test clock from its current virtual_time should be limited such that there are no more than 20 originations resulting from the advance operation on each recurring_transfer associated with the test_clock. For instance, if the recurring transfer associated with this test clock originates once every 4 weeks, you can advance the virtual_time up to 80 weeks on each API call.

sandbox/transfer/test_clock/advance

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
test_clock_id
requiredstring
Plaid’s unique identifier for a test clock.
new_virtual_time
requiredstring
The virtual timestamp on the test clock. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time
Select Language
1const request: SandboxTransferTestClockAdvanceRequest = {
2  test_clock_id: 'b33a6eda-5e97-5d64-244a-a9274110151c',
3  new_virtual_time: '2006-01-02T15:04:05Z'
4};
5try {
6  const response = await plaidClient.sandboxTransferTestClockAdvance(request);
7} catch (error) {
8  // handle error
9}
sandbox/transfer/test_clock/advance

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "mdqfuVxeoza6mhu"
3}
Was this helpful?

/sandbox/transfer/test_clock/get

Get a test clock

Use the /sandbox/transfer/test_clock/get endpoint to get a test_clock in the Sandbox environment.

sandbox/transfer/test_clock/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
test_clock_id
requiredstring
Plaid’s unique identifier for a test clock.
Select Language
1const request: SandboxTransferTestClockGetRequest = {
2  test_clock_id: 'b33a6eda-5e97-5d64-244a-a9274110151c'
3};
4try {
5  const response = await plaidClient.sandboxTransferTestClockGet(request);
6  const test_clock = response.data.test_clock;
7} catch (error) {
8  // handle error
9}
sandbox/transfer/test_clock/get

Response fields and example

test_clock
object
Defines the test clock for a transfer.
test_clock_id
string
Plaid’s unique identifier for a test clock.
virtual_time
string
The virtual timestamp on the test clock. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "test_clock": {
3    "test_clock_id": "b33a6eda-5e97-5d64-244a-a9274110151c",
4    "virtual_time": "2006-01-02T15:04:05Z"
5  },
6  "request_id": "mdqfuVxeoza6mhu"
7}
Was this helpful?

/sandbox/transfer/test_clock/list

List test clocks

Use the /sandbox/transfer/test_clock/list endpoint to see a list of all your test clocks in the Sandbox environment, by ascending virtual_time. Results are paginated; use the count and offset query parameters to retrieve the desired test clocks.

sandbox/transfer/test_clock/list

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
start_virtual_time
string
The start virtual timestamp of test clocks to return. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time
end_virtual_time
string
The end virtual timestamp of test clocks to return. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time
count
integer
The maximum number of test clocks to return.

Minimum: 1
Maximum: 25
Default: 25
offset
integer
The number of test clocks to skip before returning results.

Default: 0
Minimum: 0
Select Language
1const request: SandboxTransferTestClockListRequest = {
2  count: 2
3};
4try {
5  const response = await plaidClient.sandboxTransferTestClockList(request);
6  const test_clocks = response.data.test_clocks;
7} catch (error) {
8  // handle error
9}
sandbox/transfer/test_clock/list

Response fields and example

test_clocks
[object]
test_clock_id
string
Plaid’s unique identifier for a test clock.
virtual_time
string
The virtual timestamp on the test clock. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "test_clocks": [
3    {
4      "test_clock_id": "b33a6eda-5e97-5d64-244a-a9274110151c",
5      "virtual_time": "2006-01-02T15:04:05Z"
6    },
7    {
8      "test_clock_id": "a33a6eda-5e97-5d64-244a-a9274110152d",
9      "virtual_time": "2006-02-02T15:04:05Z"
10    }
11  ],
12  "request_id": "mdqfuVxeoza6mhu"
13}
Was this helpful?

/sandbox/income/fire_webhook

Manually fire an Income webhook

Use the /sandbox/income/fire_webhook endpoint to manually trigger a Payroll Income webhook in the Sandbox environment.

sandbox/income/fire_webhook

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
item_id
requiredstring
The Item ID associated with the verification.
user_id
string
The Plaid user_id of the User associated with this webhook, warning, or error.
webhook
requiredstring
The URL to which the webhook should be sent.
verification_status
requiredstring
VERIFICATION_STATUS_PROCESSING_COMPLETE: The income verification status processing has completed. If the user uploaded multiple documents, this webhook will fire when all documents have finished processing. Call the /income/verification/paystubs/get endpoint and check the document metadata to see which documents were successfully parsed.
VERIFICATION_STATUS_PROCESSING_FAILED: A failure occurred when attempting to process the verification documentation.
VERIFICATION_STATUS_PENDING_APPROVAL: (deprecated) The income verification has been sent to the user for review.

Possible values: VERIFICATION_STATUS_PROCESSING_COMPLETE, VERIFICATION_STATUS_PROCESSING_FAILED, VERIFICATION_STATUS_PENDING_APPROVAL
Select group for content switcher
Select Language
1const request: SandboxIncomeFireWebhookRequest = {
2  item_id: 'Rn3637v1adCNj5Dl1LG6idQBzqBLwRcRZLbgM',
3  webhook: 'https://webhook.com/',
4  verification_status: 'VERIFICATION_STATUS_PROCESSING_COMPLETE',
5};
6try {
7  const response = await plaidClient.sandboxIncomeFireWebhook(request);
8  // empty response upon success
9} catch (error) {
10  // handle error
11}
sandbox/income/fire_webhook

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "mdqfuVxeoza6mhu"
3}
Was this helpful?

auth partnerships dwolla

Add Dwolla to your app

Use Dwolla with Plaid Auth to send and receive payments

Dwolla partnership

Plaid and Dwolla have partnered to offer businesses an easier way to connect to the U.S. banking system. Plaid enables businesses to instantly authenticate a customer's bank account, giving them the ability to leverage the Dwolla API to connect to the ACH or RTP® networks for sending and receiving payments. Dwolla’s solution offers frictionless ACH or real-time payments payments for companies looking to automate their current payments process and scale their business.

With the Plaid + Dwolla integration, your users can verify their accounts in seconds by inputting their banking credentials in Plaid’s front-end module. Plaid’s mobile-friendly module handles input validation, error handling, and multi-factor authentication–providing a seamless onboarding experience to convert more users for your business.

As part of the integration, Dwolla customers can access Plaid’s full suite of APIs for clean, categorized transaction data, real-time balances, and more.

Getting started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication.

Your customers will use Link to authenticate with their financial institution and select the depository account they wish to use for ACH or RTP® transactions. From there, you'll receive a Plaid access_token, allowing you to leverage real-time balance checks and transaction data, and a Dwolla processor_token, which allows you to quickly and securely verify a bank funding source via Dwolla's API without having to store any sensitive banking information. Utilizing Plaid + Dwolla enables a seamless workflow for sending and receiving payments.

Instructions

Set up your Plaid and Dwolla accounts

You'll need accounts at both Plaid and Dwolla in order to use the Plaid + Dwolla integration. You'll also need to be a Dwolla customer in order to add a bank funding source.

First, sign up for a Dwolla account if you don't already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one. Your account will be automatically enabled for integration access.

To verify that your Plaid account is enabled for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Dwolla to enable the integration.

Use the Dwolla Sandbox to test the Plaid + Dwolla integration for free.

Complete your Plaid application profile and company profile

After connecting your Plaid and Dwolla accounts, you'll need to complete your Plaid application profile and company profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. View the /link/token/create documentation for a full list of link_token configurations.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Dwolla processor_token.

Select Language
1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onLoad: function() {
9          // The Link module finished loading.
10      },
11      onSuccess: function(public_token, metadata) {
12        // The onSuccess function is called when the user has
13        // successfully authenticated and selected an account to
14        // use.
15        //
16        // When called, you will send the public_token and the selected accounts,
17        // metadata.accounts, to your backend app server.
18
19        sendDataToBackendServer({
20           public_token: public_token,
21           accounts: metadata.accounts
22        });
23      },
24        console.log('Public Token: ' + public_token);
25        console.log('Customer-selected account ID: ' + metadata.account_id);
26      },
27      onExit: function(err, metadata) {
28        // The user exited the Link flow.
29        if (err != null) {
30            // The user encountered a Plaid API error
31            // prior to exiting.
32        }
33        // metadata contains information about the institution
34        // that the user selected and the most recent
35        // API request IDs.
36        // Storing this information can be helpful for support.
37      },
38    });
39  })();
40
41  // Trigger the authentication view
42  document.getElementById('linkButton').onclick = function() {
43    linkHandler.open();
44  };
45</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. In order to avoid any confusion about which account your user wishes to use with Dwolla, it is recommended to set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the account_id property of the account to Plaid, along with the access_token, to create a Dwolla processor_token. You'll send this token to Dwolla and they will use it to securely retrieve account and routing numbers from Plaid.

Select group for content switcher
Select Language
1const {
2  Configuration,
3  PlaidApi,
4  PlaidEnvironments,
5  ProcessorTokenCreateRequest,
6} = require('plaid');
7// Change sandbox to development to test with live users;
8// Change to production when you're ready to go live!
9const configuration = new Configuration({
10  basePath: PlaidEnvironments[process.env.PLAID_ENV],
11  baseOptions: {
12    headers: {
13      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
14      'PLAID-SECRET': process.env.PLAID_SECRET,
15      'Plaid-Version': '2020-09-14',
16    },
17  },
18});
19
20const plaidClient = new PlaidApi(configuration);
21
22try {
23  // Exchange the public_token from Plaid Link for an access token.
24  const tokenResponse = await plaidClient.itemPublicTokenExchange({
25    public_token: publicToken,
26  });
27  const accessToken = tokenResponse.access_token;
28
29  // Create a processor token for a specific account id.
30  const request: ProcessorTokenCreateRequest = {
31    access_token: accessToken,
32    account_id: accountID,
33    processor: 'dwolla',
34  };
35  const processorTokenResponse = await plaidClient.processorTokenCreate(
36    request,
37  );
38  const processorToken = processorTokenResponse.processor_token;
39} catch (error) {
40  // handle error
41}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "[Unique request ID]"
4}
Make a request to Dwolla

Once you've obtained the processor_token, you'll then pass it to Dwolla as the value of the plaidToken request parameter, along with a funding source name, to create a funding source for a Dwolla Customer:

Select Language
1POST https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C/funding-sources
2Content-Type: application/vnd.dwolla.v1.hal+json
3Accept: application/vnd.dwolla.v1.hal+json
4Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
5
6{
7  "plaidToken": "processor-sandbox-161c86dd-d470-47e9-a741-d381c2b2cb6f",
8  "name": "Jane Doe’s Checking"
9}
10
11...
12
13HTTP/1.1 201 Created
14Location: https://api-sandbox.dwolla.com/funding-sources/375c6781-2a17-476c-84f7-db7d2f6ffb31

Once you’ve received a successful response from the Dwolla API, you’ll use the unique funding source URL to identify the Customer’s bank when initiating ACH or RTP transfers.

Testing your Dwolla integration

You can create Dwolla processor_tokens in Sandbox (sandbox.plaid.com, allows testing with simulated users) or Production (production.plaid.com, requires Dwolla Production credentials). While Plaid also has a third environment, Development, used for limited live testing, it is not recommended to test this integration in the Development environment as the processor tokens created in that environment are not compatible with Dwolla's test and production environments.

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js.

For a tutorial walkthrough of creating a similar app with Dwolla support, see Account funding tutorial.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

link react native

Link React Native SDK

Reference for integrating with the Link React Native SDK

This guide covers the latest major version of the Link React Native SDK, which is version 10.x.x. Beginning September 30, 2023, all integrations must use version 9.0.1 or later in order to maintain support for Chase OAuth flows on iOS. If you are using an older version of the SDK, consult the consult the 5.x to 7.x or 6.x to 7.x migration guides. If you are using the 7.x or 8.x version of the SDK, the only migration requirement for version 9.x is to make sure you are using a compatible version of the iOS SDK (4.1.0 or later) and Xcode 14.

For information on migrating from 9.x to 10.x, see Upgrading.

Overview

Prefer to learn with code examples? A GitHub repo showing a working example Link implementation is available for this topic.

To get started with Plaid Link for React Native youʼll want to sign up for free API keys through the Plaid Developer Dashboard.

Examples of Plaid Link for React Native

Requirements

New versions of the React Native SDK are released frequently, at least once every few months. You should keep your version up-to-date to provide the best Plaid Link experience in your application.

Version Compatibility
React Native SDKAndroid SDKiOS SDKStatus
10.x.x3.10.1+>=4.1.0Active, supports Xcode 14
9.x.x3.10.1+>=4.1.0Deprecated, supports Xcode 14
8.x.x3.10.1+>=3.1.0Deprecated, supports Xcode 14
7.x.x3.2.0+>=2.0.7Deprecated, supports Xcode <=13
6.x.x3.0.0-3.1.0>=2.0.1Deprecated
5.x.x2.1.0-2.2.0>=1.1.34Deprecated
4.x.x2.0.0<=1.1.33Deprecated
3.x.x1.x.x<=1.1.33Deprecated
2.x.x0.3.x<=1.1.27Deprecated
1.x.x< 0.3.x<=1.1.24Deprecated

Getting Started

Installing the SDK

In your react-native project directory, run:

1npm install --save react-native-plaid-link-sdk

Next Steps

Opening Link

Before you can open Link, you need to first create a link_token. A link_token can be configured for different Link flows and is used to control much of Link's behavior. To see how to create a new link_token, see the API Reference entry for /link/token/create. If your React Native application will be used on Android, the link/token/create call should include the android_package_name parameter. Each time you open Link, you will need to get a new link_token from your server.

PlaidLink

PlaidLink is the the React component used to open Link from a React Native application. PlaidLink renders a Pressable component, which wraps the component you provide and intercepts onPress events to open Link.

plaidLink
onSuccess
LinkSuccessListener
A function that is called when a user successfully links an Item. The function should expect one argument. See onSuccess.
tokenConfig
LinkTokenConfiguration
A configuration used to open Link with a Link Token.
token
string
The link_token to be used to authenticate your app with Link. The link_token is created by calling /link/token/create and is a short lived, one-time use token that should be unique for each Link session. In addition to the primary flow, a link_token can be configured to launch Link in update mode. See the /link/token/create endpoint for a full list of configurations.
logLevel
LinkLogLevel
Set the level at which to log statements

Possible values: DEBUG, INFO, WARN, ERROR
extraParams
Record<string, any>
You do not need to use this field unless specifically instructed to by Plaid.
onExit
LinkExitListener
A function that is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The function should expect one argument. See onExit.
children
React.ReactNode
The underlying component to render
1<PlaidLink
2  tokenConfig={{
3    token: '#GENERATED_LINK_TOKEN#',
4  }}
5  onSuccess={(success: LinkSuccess) => {
6    console.log(success);
7  }}
8  onExit={(exit: LinkExit) => {
9    console.log(exit);
10  }}
11>
12  <Text>Add Account</Text>
13</PlaidLink>

onSuccess

The method is called when a user successfully links an Item. The onSuccess handler returns a LinkConnection class that includes the public_token, and additional Link metadata in the form of a LinkConnectionMetadata class.

onSuccess
publicToken
String
Displayed once a user has successfully linked their Item.
metadata
LinkSuccessMetadata
Displayed once a user has successfully linked their Item.
accounts
Array<LinkAccount>
A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, accounts will only include selected accounts.
id
string
The Plaid account_id
name
nullablestring
The official account name
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, it may also not match the mask that the bank displays to the user.
type
LinkAccountType
The account type. See the Account schema for a full list of possible values
subtype
LinkAccountSubtype
The account subtype. See the Account schema for a full list of possible values
verification_status
nullableLinkAccountVerificationStatus
Indicates an Item's micro-deposit-based verification status.
pending_automatic_verification
The Item is pending automatic verification
pending_manual_verification
The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the two amounts.
automatically_verified
The Item has successfully been automatically verified
manually_verified
The Item has successfully been manually verified
verification_expired
Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed
The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.
null
The Item is not using micro-deposit verification.
institution
nullableobject
An institution object. If the Item was created via Same-Day micro-deposit verification, will be null.
name
string
The full institution name, such as 'Wells Fargo'
id
string
The Plaid institution identifier
linkSessionId
nullableString
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
metadataJson
nullableMap
The data directly returned from the server with no client side changes.
1const onSuccess = (success: LinkSuccess) => {
2  fetch('https://yourserver.com/exchange_public_token', {
3    method: 'POST',
4    headers: {
5      "Content-Type": "application/json",
6    },
7    body: JSON.Stringify({
8      publicToken: linkSuccess.publicToken,
9      accounts: linkSuccess.metadata.accounts,
10      institution: linkSuccess.metadata.institution,
11      linkSessionId: linkSuccess.metadata.linkSessionId,
12    }),
13  });
14};

onExit

The onExit handler is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The PlaidError returned from the onExit handler is meant to help you guide your users after they have exited Link. We recommend storing the error and metadata information server-side in a way that can be associated with the user. You’ll also need to include this and any other relevant info in Plaid Support requests for the user.

onExit
error
LinkError
An object that contains the error type, error code, and error message of the error that was last encountered by the user. If no error was encountered, error will be null.
displayMessage
nullableString
A user-friendly representation of the error code. null if the error is not related to user action. This may change over time and is not safe for programmatic use.
errorCode
LinkErrorCode
The particular error code. Each errorType has a specific set of errorCodes. A code of 499 indicates a client-side exception.
errorType
LinkErrorType
A broad categorization of the error.
errorMessage
String
A developer-friendly representation of the error code.
errorJson
nullableString
The data directly returned from the server with no client side changes.
metadata
Map<String, Object>
An object containing information about the exit event
linkSessionId
nullableString
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
institution
nullableLinkInstitution
An institution object. If the Item was created via Same-Day micro-deposit verification, will be null.
name
string
The full institution name, such as 'Wells Fargo'
id
string
The Plaid institution identifier
status
nullableLinkExitMetadataStatus
The point at which the user exited the Link flow. One of the following values
requires_questions
User prompted to answer security questions
requires_selections
User prompted to answer multiple choice question(s)
requires_recaptcha
User prompted to solve a reCAPTCHA challenge
requires_code
User prompted to provide a one-time passcode
choose_device
User prompted to select a device on which to receive a one-time passcode
requires_credentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution
requires_account_selection
User prompted to select one or more financial accounts to share
requires_oauth
User prompted to enter an OAuth flow
institution_not_found
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
unknown
An exit status that is not handled by the current version of the SDK
requestId
nullableString
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation
metadataJson
nullableMap
The data directly returned from the server with no client side changes.
1const onExit = (linkExit: LinkExit) => {
2  supportHandler.report({
3    error: linkExit.error,
4    institution: linkExit.metadata.institution,
5    linkSessionId: linkExit.metadata.linkSessionId,
6    requestId: linkExitlinkExit.metadata.requestId,
7    status: linkExit.metadata.status,
8  });
9};

onEvent

The React Native Plaid module emits onEvent events throughout the account linking process. To receive these events use the usePlaidEmitter hook.

The onEvent callback is called at certain points in the Link flow. Unlike the handlers for onSuccess and onExit, the onEvent handler is initialized as a global lambda passed to the Plaid class. OPEN events will be sent immediately upon Link’s opening, and remaining events will be sent by the time onSuccess or onExit is called. If you need the exact time when an event happened, use the timestamp property.
The following onEvent callbacks are stable, which means that they will not be deprecated or changed: OPEN, EXIT, HANDOFF, SELECT_INSTITUTION, ERROR, BANK_INCOME_INSIGHTS_COMPLETED, IDENTITY_VERIFICATION_PASS_SESSION, IDENTITY_VERIFICATION_FAIL_SESSION. The remaining callback events are informational and subject to change.

onEvent
eventName
LinkEventName
A string representing the event that has just occurred in the Link flow.
BANK_INCOME_INSIGHTS_COMPLETED
The user has completed the Assets and Bank Income Insights flow.
CLOSE_OAUTH
The user closed the third-party website or mobile app without completing the OAuth flow.
ERROR
A recoverable error occurred in the Link flow, see the error_code metadata.
EXIT
The user has exited without completing the Link flow and the onExit callback is fired.
FAIL_OAUTH
The user encountered an error while completing the third-party's OAuth login flow.
HANDOFF
The user has exited Link after successfully linking an Item.
IDENTITY_VERIFICATION_START_STEP
The user has started a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_PASS_STEP
The user has passed a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_FAIL_STEP
The user has failed a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_PENDING_REVIEW_STEP
The user has reached the pending review state.
IDENTITY_VERIFICATION_CREATE_SESSION
The user has started a new Identity Verification session.
IDENTITY_VERIFICATION_RESUME_SESSION
The user has resumed an existing Identity Verification session.
IDENTITY_VERIFICATION_PASS_SESSION
The user has successfully completed their Identity Verification session.
IDENTITY_VERIFICATION_PENDING_REVIEW_SESSION
The user has completed their Identity Verification session, which is now in a pending review state.
IDENTITY_VERIFICATION_FAIL_SESSION
The user has failed their Identity Verification session.
IDENTITY_VERIFICATION_OPEN_UI
The user has opened the UI of their Identity Verification session.
IDENTITY_VERIFICATION_RESUME_UI
The user has resumed the UI of their Identity Verification session.
IDENTITY_VERIFICATION_CLOSE_UI
The user has closed the UI of their Identity Verification session.
MATCHED_SELECT_INSTITUTION
The user selected an institution that was presented as a matched institution. This event can be emitted either during the Returning User Experience flow or if the institution's routing_number was provided when calling /link/token/create. To distinguish between the two scenarios, see metadata.matchReason.
MATCHED_SELECT_VERIFY_METHOD
The user selected a verification method for a matched institution. This event is emitted only during the Returning User Experience flow.
OPEN
The user has opened Link.
OPEN_MY_PLAID
The user has opened my.plaid.com. This event is only sent when Link is initialized with Assets as a product.
OPEN_OAUTH
The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.
SEARCH_INSTITUTION
The user has searched for an institution.
SELECT_BRAND
The user selected a brand, e.g. Bank of America. The SELECT_BRAND event is only emitted for large financial institutions with multiple online banking portals.
SELECT_DEGRADED_INSTITUTION
The user selected an institution with a DEGRADED health status and was shown a corresponding message.
SELECT_DOWN_INSTITUTION
The user selected an institution with a DOWN health status and was shown a corresponding message.
SELECT_INSTITUTION
The user selected an institution.
SUBMIT_ACCOUNT_NUMBER
The user has submitted an account number. This event emits the account_number_mask metadata to indicate the mask of the account number the user provided.
SUBMIT_CREDENTIALS
The user has submitted credentials.
SUBMIT_MFA
The user has submitted MFA.
SUBMIT_ROUTING_NUMBER
The user has submitted routing number. This event emits the routing_number metadata to indicate user's routing number.
TRANSITION_VIEW
The TRANSITION_VIEW event indicates that the user has moved from one view to the next.
VIEW_DATA_TYPES
The user has viewed data types on the data transparency consent pane.
UNKNOWN
The UNKNOWN event indicates that the event is not handled by the current version of the SDK.
metadata
LinkEventMetadata
An object containing information about the event.
submitAccountNumber
String
The account number mask extracted from the user-provided account number. If the user-inputted account number is four digits long, account_number_mask is empty. Emitted by SUBMIT_ACCOUNT_NUMBER.
errorCode
String
The error code that the user encountered. Emitted by: ERROR, EXIT.
errorMessage
String
The error message that the user encountered. Emitted by: ERROR, EXIT.
errorType
String
The error type that the user encountered. Emitted by: ERROR, EXIT.
exitStatus
String
The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT.
institutionId
String
The ID of the selected institution. Emitted by: all events.
institutionName
String
The name of the selected institution. Emitted by: all events.
institutionSearchQuery
String
The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.
isUpdateMode
String
Indicates if the current Link session is an update mode session. Emitted by: OPEN.
matchReason
nullablestring
The reason this institution was matched, which will be either returning_user or routing_number. Emitted by: MATCHED_SELECT_INSTITUTION.
routingNumber
Optional<String>
The routing number submitted by user at the micro-deposits routing number pane. Emitted by SUBMIT_ROUTING_NUMBER.
linkSessionId
String
The linkSessionId is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: all events.
mfaType
String
If set, the user has encountered one of the following MFA types: code device questions selections. Emitted by: SUBMIT_MFA and TRANSITION_VIEW when view_name is MFA.
requestId
String
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
selection
String
Either the verification method for a matched institution selected by the user or the Auth Type Select flow type selected by the user. If selection is used to describe selected verification method, then possible values are phoneotp or password; if selection is used to describe the selected Auth Type Select flow, then possible values are flow_type_manual or flow_type_instant. Emitted by: MATCHED_SELECT_VERIFY_METHOD and SELECT_AUTH_TYPE.
timestamp
String
An ISO 8601 representation of when the event occurred. For example, 2017-09-14T14:42:19.350Z. Emitted by: all events.
viewName
LinkEventViewName
The name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW.
ACCEPT_TOS
The view showing Terms of Service in the identity verification flow.
CONNECTED
The user has connected their account.
CONSENT
We ask the user to consent to the privacy policy.
CREDENTIAL
Asking the user for their account credentials.
DATA_TRANSPARENCY
We disclose the data types being shared.
DATA_TRANSPARENCY_CONSENT
We ask the user to consent to the privacy policy and disclose data types being shared.
DOCUMENTARY_VERIFICATION
The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor).
ERROR
An error has occurred.
EXIT
Confirming if the user wishes to close Link.
KYC_CHECK
The view representing the "know your customer" step in the identity verification flow.
LOADING
Link is making a request to our servers.
MATCHED_CONSENT
We ask the matched user to consent to the privacy policy and SMS terms.
MATCHED_CREDENTIAL
We ask the matched user for their account credentials to a matched institution.
MATCHED_MFA
We ask the matched user for MFA authentication to verify their identity.
MFA
The user is asked by the institution for additional MFA authentication.
NUMBERS
The user is asked to insert their account and routing numbers.
OAUTH
The user is informed they will authenticate with the financial institution via OAuth.
RECAPTCHA
The user was presented with a Google reCAPTCHA to verify they are human.
RISK_CHECK
The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor).
SCREENING
The watchlist screening step in the identity verification flow.
SELECT_ACCOUNT
We ask the user to choose an account.
SELECT_AUTH_TYPE
The user is asked to choose whether to Link instantly or manually (i.e., with micro-deposits).
SELECT_BRAND
The user is asked to select a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.
SELECT_INSTITUTION
We ask the user to choose their institution.
SELFIE_CHECK
The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.
UPLOAD_DOCUMENTS
The user is asked to upload documents (for Income verification).
VERIFY_SMS
The SMS verification step in the identity verification flow.
1usePlaidEmitter((event) => {
2  console.log(event);
3});

OAuth

Using Plaid Link with an OAuth flow requires some additional setup instructions. For details, see the OAuth guide.

Upgrading

  • When upgrading from 9.x to 10.x, you should remove any invocation of useDeepLinkRedirector on iOS, as it has been removed from the SDK, since it is no longer required for handling Universal Links. You must make sure you are using a compatible version of React Native (0.66.0 or higher) and the Plaid iOS SDK (see the version compatibility chart on GitHub).
  • To upgrade from version 6.x to 7.x or 8.x, see the 6.x to 7.x migration guide.
  • To upgrade from version 5.x to 7.x or 8.x, see the 5.x to 7.x migration guide.
  • The only difference between version 7.x and 8.x is that 8.x adds support for Xcode 14. No code changes are required to upgrade from 7.x to 8.x, although you must convert to an Xcode 14 toolchain.
  • No code changes are required to upgrade from 8.x to 9.x, although you must make sure you are using a compatible version of the Plaid iOS SDK (4.1.0 or higher).

assets

Introduction to Assets

Learn how to use Assets to access users' financial information for loan underwriting.

Explore API

Prefer to learn by watching? A video guide is available for this topic.

Overview

Assets data is used to determine whether a user has enough assets to qualify for a loan. Plaid's Assets product allows you to access a user's Asset Report via the /asset_report/get (JSON) and /asset_report/pdf/get (PDF) endpoints. Asset Reports are created on a per-user basis and include a snapshot of information about a user's identity, transaction history, account balances, and more.

For a fuller view of a borrower's financial situation, Assets can be used with Bank Income, which provides user-permissioned income streams derived from deposit activity.

Assets flow

There are a few steps you will need to take to obtain an Asset Report for a particular user.

  1. First, using Link, create Items for each of the user's financial institutions; in doing so, you will obtain an access_token for each institution. You can use these tokens to obtain an Asset Report as long as the access_token was generated with assets included in Link's product array. With Assets, the user, upon using Link to authenticate with their financial institution, will need to provide consent for Plaid to access account balances, account holder information, and transaction history for that institution. Should the user revoke access via my.plaid.com, Plaid will notify you via a webhook.

  2. Once you have the required access_tokens, call the /asset_report/create endpoint to create an Asset Report. Note that Asset Reports are not created instantly. When the Asset Report is ready, you will be notified via a PRODUCT_READY webhook. If low latency is important to your use case, you can call /asset_report/create with options.add_ons set to ["fast_assets"]. This will cause Plaid to create two versions of the Asset Report: one with only current and available balance and identity information, and then later on the complete Asset Report. You will receive separate webhooks for each version of the Asset Report.

  3. After receiving the PRODUCT_READY webhook, you can retrieve an Asset Report in JSON format by calling the /asset_report/get endpoint. To retrieve an Asset Report in PDF format, call the /asset_report/pdf/get endpoint. To retrieve an Asset Report with cleaned and categorized transactions as well as additional information about merchants and locations in JSON format, call the /asset_report/get endpoint with include_insights=true. If you enabled Fast Assets when calling /asset_report/create, you can request the Fast version of the Asset Report by calling /asset_report/get with fast_report=true.

  4. Sometimes, third party auditors need to see Asset Reports to audit lenders' decision making processes. To provide an Audit Copy of an Asset Report to a requesting third party, call the /asset_report/audit_copy/create endpoint and provide the auditor with an audit_copy_token. The auditor needs to be integrated with Plaid in order to view Audit Copies. Currently, Fannie Mae, Freddie Mac, and Ocrolus are the only auditors integrated with Plaid.

1{
2  "report": {
3    "asset_report_id": "bf3a0490-344c-4620-a219-2693162e4b1d",
4    "client_report_id": "123abc",
5    "date_generated": "2020-06-05T22:47:53Z",
6    "days_requested": 2,
7    "items": [
8      {
9        "accounts": [
10          {
11            "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
12            "balances": {
13              "available": 200,
14              "current": 210,
15              "iso_currency_code": "USD",
16              "limit": null,
17              "unofficial_currency_code": null
18            },
19            "days_available": 2,
20            "historical_balances": [
21              {
22                "current": 210,
23                "date": "2020-06-04",
24                "iso_currency_code": "USD",
25                "unofficial_currency_code": null
26              },
27              {
28                "current": 210,
29                "date": "2020-06-03",
30                "iso_currency_code": "USD",
31                "unofficial_currency_code": null
32              }
33            ],
34            "mask": "1111",
35            "name": "Plaid Saving",
36            "official_name": "Plaid Silver Standard 0.1% Interest Saving",
37            "owners": [
38              {
39                "addresses": [
40                  {
41                    "data": {
42                      "city": "Malakoff",
43                      "country": "US",
44                      "postal_code": "14236",
45                      "region": "NY",
46                      "street": "2992 Cameron Road"
47                    },
48                    "primary": true
49                  },
50                  {
51                    "data": {
52                      "city": "San Matias",
53                      "country": "US",
54                      "postal_code": "93405-2255",
55                      "region": "CA",
56                      "street": "2493 Leisure Lane"
57                    },
58                    "primary": false
59                  }
60                ],
61                "emails": [
62                  {
63                    "data": "accountholder0@example.com",
64                    "primary": true,
65                    "type": "primary"
66                  },
67                  {
68                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
69                    "primary": false,
70                    "type": "other"
71                  }
72                ],
73                "names": ["Alberta Bobbeth Charleson"],
74                "phone_numbers": [
75                  {
76                    "data": "1112223333",
77                    "primary": false,
78                    "type": "home"
79                  },
80                  {
81                    "data": "1112225555",
82                    "primary": false,
83                    "type": "mobile1"
84                  }
85                ]
86              }
87            ],
88            "ownership_type": null,
89            "subtype": "savings",
90            "transactions": [],
91            "type": "depository"
92          },
93          {
94            "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
95            "balances": {
96              "available": null,
97              "current": 56302.06,
98              "iso_currency_code": "USD",
99              "limit": null,
100              "unofficial_currency_code": null
101            },
102            "days_available": 2,
103            "historical_balances": [],
104            "mask": "8888",
105            "name": "Plaid Mortgage",
106            "official_name": null,
107            "owners": [
108              {
109                "addresses": [
110                  {
111                    "data": {
112                      "city": "Malakoff",
113                      "country": "US",
114                      "postal_code": "14236",
115                      "region": "NY",
116                      "street": "2992 Cameron Road"
117                    },
118                    "primary": true
119                  },
120                  {
121                    "data": {
122                      "city": "San Matias",
123                      "country": "US",
124                      "postal_code": "93405-2255",
125                      "region": "CA",
126                      "street": "2493 Leisure Lane"
127                    },
128                    "primary": false
129                  }
130                ],
131                "emails": [
132                  {
133                    "data": "accountholder0@example.com",
134                    "primary": true,
135                    "type": "primary"
136                  },
137                  {
138                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
139                    "primary": false,
140                    "type": "other"
141                  }
142                ],
143                "names": ["Alberta Bobbeth Charleson"],
144                "phone_numbers": [
145                  {
146                    "data": "1112223333",
147                    "primary": false,
148                    "type": "home"
149                  },
150                  {
151                    "data": "1112225555",
152                    "primary": false,
153                    "type": "mobile1"
154                  }
155                ]
156              }
157            ],
158            "ownership_type": null,
159            "subtype": "mortgage",
160            "transactions": [],
161            "type": "loan"
162          },
163          {
164            "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
165            "balances": {
166              "available": null,
167              "current": 410,
168              "iso_currency_code": "USD",
169              "limit": null,
170              "unofficial_currency_code": null
171            },
172            "days_available": 2,
173            "historical_balances": [
174              {
175                "current": 410,
176                "date": "2020-06-04",
177                "iso_currency_code": "USD",
178                "unofficial_currency_code": null
179              },
180              {
181                "current": 410,
182                "date": "2020-06-03",
183                "iso_currency_code": "USD",
184                "unofficial_currency_code": null
185              }
186            ],
187            "mask": "3333",
188            "name": "Plaid Credit Card",
189            "official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
190            "owners": [
191              {
192                "addresses": [
193                  {
194                    "data": {
195                      "city": "Malakoff",
196                      "country": "US",
197                      "postal_code": "14236",
198                      "region": "NY",
199                      "street": "2992 Cameron Road"
200                    },
201                    "primary": true
202                  },
203                  {
204                    "data": {
205                      "city": "San Matias",
206                      "country": "US",
207                      "postal_code": "93405-2255",
208                      "region": "CA",
209                      "street": "2493 Leisure Lane"
210                    },
211                    "primary": false
212                  }
213                ],
214                "emails": [
215                  {
216                    "data": "accountholder0@example.com",
217                    "primary": true,
218                    "type": "primary"
219                  },
220                  {
221                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
222                    "primary": false,
223                    "type": "other"
224                  }
225                ],
226                "names": ["Alberta Bobbeth Charleson"],
227                "phone_numbers": [
228                  {
229                    "data": "1112223333",
230                    "primary": false,
231                    "type": "home"
232                  },
233                  {
234                    "data": "1112225555",
235                    "primary": false,
236                    "type": "mobile1"
237                  }
238                ]
239              }
240            ],
241            "ownership_type": null,
242            "subtype": "credit card",
243            "transactions": [],
244            "type": "credit"
245          }
246        ],
247        "date_last_updated": "2020-06-05T22:47:52Z",
248        "institution_id": "ins_3",
249        "institution_name": "Chase",
250        "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6"
251      }
252    ],
253    "user": {
254      "client_user_id": "123456789",
255      "email": "accountholder0@example.com",
256      "first_name": "Alberta",
257      "last_name": "Charleson",
258      "middle_name": "Bobbeth",
259      "phone_number": "111-222-3333",
260      "ssn": "123-45-6789"
261    }
262  },
263  "request_id": "eYupqX1mZkEuQRx",
264  "warnings": []
265}

The report field of the above object contains the body of the Asset Report. This field consists of several subfields that contain information about the date and time the Asset Report was created; data submitted about the user; and information about Items, containing the user's historical balances, identity information, and more for each of the user's financial institutions. For a full explanation of the report field and its subfields, consult the API Reference.

Assets webhooks

When you create an Asset Report, Plaid aggregates account balances, account holder identity information, and transaction history for the duration specified. If you attempt to retrieve an Asset Report before the requested data has been collected, you’ll receive a response with the HTTP status code 400 and a Plaid error code of PRODUCT_NOT_READY.

To remove the need for polling, Plaid sends a webhook to the URL you supplied when creating the Asset Report once the Report has been generated. If generation fails, the webhook will indicate why. For examples of webhooks corresponding to successful and unsuccessful Asset Report generation, see the API Reference for Assets webhooks.

Refreshing Asset Reports

Asset Reports can either be created or removed; they cannot be updated. To retrieve up-to-date information about users' transactions and balances, call the /asset_report/refresh endpoint. This endpoint, when used, creates a new Asset Report based on the corresponding existing Asset Report.

Getting an Asset Report for an existing Item

If your user has already connected their account to your application for a different product, you can add Assets to the existing Item via update mode.

To do so, in the /link/token/create request described in the Assets flow, populate the access_token field with the access token for the Item, and set the products array to ["assets"]. If the user connected their account less than two years ago, they can bypass the Link credentials pane and complete just the Asset Report consent step. Otherwise, they will be prompted to complete the full Link flow.

Testing Assets

Assets can be tested in Sandbox without any additional permissions. In order to test Assets against live Items in Development or Production, you will need to first request access by submitting a product access request Support ticket explaining your use case.

Plaid provides a GitHub repo with test data for testing Assets in Sandbox, beyond that provided by the default Sandbox user. For more information on configuring custom Sandbox data, see Configuring the custom user account.

Attributes library

Plaid provides a GitHub Credit attributes library with Python scripts that can be used to derive various useful information from Asset Reports.

Next steps

To learn more about building with Assets, see Create an Asset Report and the API Reference.

For a more detailed overview of the steps involved in creating a full implementation of Plaid Assets, see the Plaid Assets Solution Guide.

If you're ready to launch to Production, see the Launch checklist.

assets partnerships

Assets Partners

Find providers who have partnered with Plaid to provide Assets verification

Overview

Ocrolus partners with Plaid to provide digitized Asset documentation verification (US only). For instructions and more details, see the Ocrolus partnership documentation.

For more information, see the list of partners in the Developer Dashboard.

auth partnerships moov

Add Moov to your app

Use Moov with Plaid Auth to send and receive payments!

Partnership Moov logo

Overview

Plaid and Moov’s partnership allows mutual customers to seamlessly link bank accounts so they can move money faster. Moov’s customers can now verify their bank accounts through Plaid’s front-end module. To enable instant account verification, Moov customers will generate a Processor token on behalf of each user. This allows Moov to retrieve bank account details directly from Plaid, so Moov’s customers won’t need to directly handle sensitive bank information.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Moov account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Moov processor_token, which allows you to quickly and securely verify a bank funding source via Moov's API without having to store any sensitive banking information. Utilizing Plaid + Moov enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Moov in order to use the Plaid + Moov integration. You'll also need to enable your Plaid account for the Moov integration.

First, you will need to work with the Moov team to sign up for a Moov account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Moov to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Moov processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Moov, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Moov processor_token. You'll send this token to Moov and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Moov processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'moov',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Moov Production credentials prior to initiating live payment transactions in the Moov API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

auth partnerships adyen

Add Adyen to your app

Use Adyen with Plaid Auth to send and receive payments!

Partnership Adyen logo

Overview

Plaid and Adyen have partnered to allow businesses to verify bank accounts and reduce returns through an end-to-end ACH solution. Plaid enables consumers and businesses to instantly authenticate their bank account including account and routing number as well as the current account balance. The account details are delivered directly to Adyen via a secure tokenized integration. Adyen processes the ACH transaction (supports both ACH credits and ACH debits), integrating the payment or payout into your existing settlement and reconciliation process with Adyen.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Adyen account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Adyen processor_token, which allows you to quickly and securely verify a bank funding source via Adyen's API without having to store any sensitive banking information. Utilizing Plaid + Adyen enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Adyen in order to use the Plaid + Adyen integration. You'll also need to enable your Plaid account for the Adyen integration.

First, you will need to work with the Adyen team to sign up for a Adyen account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Adyen to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Adyen processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Adyen, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Adyen processor_token. You'll send this token to Adyen and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Adyen processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'adyen',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Adyen Production credentials prior to initiating live payment transactions in the Adyen API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

api products identity verification

Identity Verification

API reference for Identity Verification endpoints and webhooks

Endpoints
/identity_verification/createCreate a new identity verification
/identity_verification/getRetrieve a previously created identity verification
/identity_verification/listFilter and list identity verifications
/identity_verification/retryAllow a user to retry an identity verification
Webhooks
STATUS_UPDATEDThe status of an identity verification has been updated
STEP_UPDATEDA step in the identity verification process has been completed
RETRIEDAn identity verification has been retried

Endpoints

/identity_verification/create

Create a new identity verification

Create a new Identity Verification for the user specified by the client_user_id field. The requirements and behavior of the verification are determined by the template_id provided. If you don't know whether the associated user already has an active Identity Verification, you can specify "is_idempotent": true in the request body. With idempotency enabled, a new Identity Verification will only be created if one does not already exist for the associated client_user_id and template_id. If an Identity Verification is found, it will be returned unmodified with an 200 OK HTTP status code.
You can also use this endpoint to supply information you already have collected about the user; if any of these fields are specified, the screens prompting the user to enter them will be skipped during the Link flow.

identity_verification/create

Request fields and example

client_user_id
string
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
is_shareable
requiredboolean
A flag specifying whether you would like Plaid to expose a shareable URL for the verification being created.
template_id
requiredstring
ID of the associated Identity Verification template.
gave_consent
requiredboolean
A flag specifying whether the end user has already agreed to a privacy policy specifying that their data will be shared with Plaid for verification purposes.
If gave_consent is set to true, the accept_tos step will be marked as skipped and the end user's session will start at the next step requirement.

Default: false
user
object
User information collected outside of Link, most likely via your own onboarding process.
Each of the following identity fields are optional:
email_address
phone_number
date_of_birth
name
address
id_number
Specifically, these fields are optional in that they can either be fully provided (satisfying every required field in their subschema) or omitted from the request entirely by not providing the key or value. Providing these fields via the API will result in Link skipping the data collection process for the associated user. All verification steps enabled in the associated Identity Verification Template will still be run. Verification steps will either be run immediately, or once the user completes the accept_tos step, depending on the value provided to the gave_consent field. If you are not using the shareable URL feature, you can optionally provide these fields via /link/token/create instead; both /identity_verification/create and /link/token/create are valid ways to provide this information. Note that if you provide a non-null user data object via /identity_verification/create, any user data fields entered via /link/token/create for the same client_user_id will be ignored when prefilling Link.
email_address
string
A valid email address.

Format: email
phone_number
string
A phone number in E.164 format.
date_of_birth
string
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
name
object
You can use this field to pre-populate the user's legal name; if it is provided here, they will not be prompted to enter their name in the identity verification attempt.
given_name
requiredstring
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
requiredstring
A string with at least one non-whitespace character, with a max length of 100 characters.
address
object
Home address for the user. For more context on this field, see Input Validation by Country.
street
requiredstring
The primary street portion of an address. If the user has submitted their address, this field will always be filled.
street2
string
Extra street information, like an apartment or suite number.
city
requiredstring
City from the end user's address
region
string
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
string
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
requiredstring
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
id_number
object
ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.
value
requiredstring
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
requiredstring
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
client_user_id
deprecatedstring
Specifying user.client_user_id is deprecated. Please provide client_user_id at the root level instead.

Min length: 1
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
is_idempotent
boolean
An optional flag specifying how you would like Plaid to handle attempts to create an Identity Verification when an Identity Verification already exists for the provided client_user_id and template_id. If idempotency is enabled, Plaid will return the existing Identity Verification. If idempotency is disabled, Plaid will reject the request with a 400 Bad Request status code if an Identity Verification already exists for the supplied client_user_id and template_id.
Select Language
1const request: IdentityVerificationCreateRequest = {
2  client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3  is_shareable: true,
4  template_id: 'idv_52xR9LKo77r1Np',
5  gave_consent: true,
6  user: {
7    email_address: 'acharleston@email.com',
8    phone_number: '+11234567890',
9    date_of_birth: '1975-01-18',
10    name: {
11      given_name: 'Anna',
12      family_name: 'Charleston',
13    },
14    address: {
15      street: '100 Market Street',
16      street2: 'Apt 1A',
17      city: 'San Francisco',
18      region: 'CA',
19      postal_code: '94103',
20      country: 'US',
21    },
22    id_number: {
23      value: '123456789',
24      type: 'us_ssn',
25    },
26  },
27};
28try {
29  const response = await client.identityVerificationCreate(request);
30} catch (error) {
31  // handle error
32}
identity_verification/create

Response fields and example

id
string
ID of the associated Identity Verification attempt.
client_user_id
string
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
completed_at
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
previous_attempt_id
nullablestring
The ID for the Identity Verification preceding this session. This field will only be filled if the current Identity Verification is a retry of a previous attempt.
shareable_url
nullablestring
A shareable URL that can be sent directly to the user to complete verification
template
object
The resource ID and version number of the template configuring the behavior of a given identity verification.
id
string
ID of the associated Identity Verification template.
version
integer
Version of the associated Identity Verification template.
user
object
The identity data that was either collected from the user or provided via API in order to perform an identity verification.
phone_number
nullablestring
A phone number in E.164 format.
date_of_birth
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
ip_address
nullablestring
An IPv4 or IPV6 address.
email_address
nullablestring
A valid email address.

Format: email
name
nullableobject
The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.
given_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
address
nullableobject
Even if an address has been collected, some fields may be null depending on the region's addressing system. For example:
Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include postal code
street
nullablestring
The primary street portion of an address. If the user has submitted their address, this field will always be filled.
street2
nullablestring
Extra street information, like an apartment or suite number.
city
nullablestring
City from the end user's address
region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
nullablestring
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
id_number
nullableobject
ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.
value
string
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
string
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
status
string
The status of this Identity Verification attempt.
active - The Identity Verification attempt is incomplete. The user may have completed part of the session, but has neither failed or passed.
success - The Identity Verification attempt has completed, passing all steps defined to the associated Identity Verification template
failed - The user failed one or more steps in the session and was told to contact support.
expired - The Identity Verification attempt was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future.
canceled - The Identity Verification attempt was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed.
pending_review - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review.

Possible values: active, success, failed, expired, canceled, pending_review
steps
object
Each step will be one of the following values:
active - This step is the user's current step. They are either in the process of completing this step, or they recently closed their Identity Verification attempt while in the middle of this step. Only one step will be marked as active at any given point.
success - The Identity Verification attempt has completed this step.
failed - The user failed this step. This can either call the user to fail the session as a whole, or cause them to fallback to another step depending on how the Identity Verification template is configured. A failed step does not imply a failed session.
waiting_for_prerequisite - The user needs to complete another step first, before they progress to this step. This step may never run, depending on if the user fails an earlier step or if the step is only run as a fallback.
not_applicable - This step will not be run for this session.
skipped - The retry instructions that created this Identity Verification attempt specified that this step should be skipped.
expired - This step had not yet been completed when the Identity Verification attempt as a whole expired.
canceled - The Identity Verification attempt was canceled before the user completed this step.
pending_review - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review.
manually_approved - The step was manually overridden to pass by a team member in the dashboard.
manually_rejected - The step was manually overridden to fail by a team member in the dashboard.
accept_tos
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
verify_sms
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
kyc_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
documentary_verification
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
selfie_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
watchlist_screening
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
risk_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
documentary_verification
nullableobject
Data, images, analysis, and results from the documentary_verification step. This field will be null unless steps.documentary_verification has reached a terminal state of either success or failed.
status
string
The outcome status for the associated Identity Verification attempt's documentary_verification step. This field will always have the same value as steps.documentary_verification.
documents
[object]
An array of documents submitted to the documentary_verification step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type.
Note: Plaid will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within documents. If the overall documentary_verification is failed, the user has exhausted their retry attempts.
status
string
An outcome status for this specific document submission. Distinct from the overall documentary_verification.status that summarizes the verification outcome from one or more documents.

Possible values: success, failed, manually_approved
attempt
integer
The attempt field begins with 1 and increments with each subsequent document upload.
images
object
URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the GET request for the associated Identity Verification attempt. A new expiring URL is generated with each request, so you can always rerequest the Identity Verification attempt if one of your URLs expires.
original_front
nullablestring
Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document.
original_back
nullablestring
Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected.
cropped_front
nullablestring
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document.
cropped_back
nullablestring
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected.
face
nullablestring
Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo.
extracted_data
nullableobject
Data extracted from a user-submitted document.
id_number
nullablestring
Alpha-numeric ID number extracted via OCR from the user's document image.
category
string
The type of identity document detected in the images provided. Will always be one of the following values:
drivers_license - A driver's license for the associated country
id_card - A general national identification card, distinct from driver's licenses
passport - A passport for the associated country
residence_permit_card - An identity document permitting a foreign citizen to temporarily reside in the associated country
resident_card - An identity document permitting a foreign citizen to permanently reside in the associated country
Note: This value may be different from the ID type that the user selects within Link. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say passport

Possible values: drivers_license, id_card, passport, residence_permit_card, resident_card
expiration_date
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
issuing_country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
issuing_region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
date_of_birth
nullablestring
A date extracted from the document in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
address
nullableobject
The address extracted from the document. The address must at least contain the following fields to be a valid address: street, city, country. If any are missing or unable to be extracted, the address will be null.
region, and postal_code may be null based on the addressing system. For example:
Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include postal code
Note: Optical Character Recognition (OCR) technology may sometimes extract incorrect data from a document.
street
string
The full street address extracted from the document.
city
string
City extracted from the document.
region
nullablestring
An ISO 3166-2 subdivision code extracted from the document. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
nullablestring
The postal code extracted from the document. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
string
Valid, capitalized, two-letter ISO code representing the country extracted from the document. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
analysis
object
High level descriptions of how the associated document was processed. If a document fails verification, the details in the analysis object should help clarify why the document was rejected.
authenticity
string
High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction.
For example, most identity documents have formatting rules like the following:
The image of the person's face must have a certain contrast in order to highlight skin tone
The subject in the document's image must remove eye glasses and pose in a certain way
The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules
Security features like watermarks and background patterns must be present
So a match status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document.

Possible values: match, partial_match, no_match, no_data
image_quality
string
A high level description of the quality of the image the user submitted.
For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks.
Note: By default, Plaid will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality.

Possible values: high, medium, low
extracted_data
nullableobject
Analysis of the data extracted from the submitted document.
name
string
A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to identity verification attempt.

Possible values: match, partial_match, no_match
date_of_birth
string
A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the identity verification attempt.

Possible values: match, partial_match, no_match
expiration_date
string
A description of whether the associated document was expired when the verification was performed.
Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be no_data.

Possible values: not_expired, expired, no_data
issuing_country
string
A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Plaid.
Note: You can configure whether a no_match on issuing_country fails the documentary_verification by editing your Plaid Template.

Possible values: match, no_match
redacted_at
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
selfie_check
nullableobject
Additional information for the selfie_check step. This field will be null unless steps.selfie_check has reached a terminal state of either success or failed.
status
string
The outcome status for the associated Identity Verification attempt's selfie_check step. This field will always have the same value as steps.selfie_check.

Possible values: success, failed
selfies
[object]
An array of selfies submitted to the selfie_check step. Each entry represents one user submission.
status
string
An outcome status for this specific selfie. Distinct from the overall selfie_check.status that summarizes the verification outcome from one or more selfies.

Possible values: success, failed
attempt
integer
The attempt field begins with 1 and increments with each subsequent selfie upload.
capture
object
The image or video capture of a selfie. Only one of image or video URL will be populated per selfie.
image_url
nullablestring
Temporary URL for downloading an image selfie capture.
video_url
nullablestring
Temporary URL for downloading a video selfie capture.
analysis
object
High level descriptions of how the associated selfie was processed. If a selfie fails verification, the details in the analysis object should help clarify why the selfie was rejected.
document_comparison
string
Information about the comparison between the selfie and the document (if documentary verification also ran).

Possible values: match, no_match, no_input
kyc_check
nullableobject
Additional information for the kyc_check step. This field will be null unless steps.kyc_check has reached a terminal state of either success or failed.
status
string
The outcome status for the associated Identity Verification attempt's kyc_check step. This field will always have the same value as steps.kyc_check.
address
object
Result summary object specifying how the address field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
po_box
string
Field describing whether the associated address is a post office box. Will be yes when a P.O. box is detected, no when Plaid confirmed the address is not a P.O. box, and no_data when Plaid was not able to determine if the address is a P.O. box.

Possible values: yes, no, no_data
type
string
Field describing whether the associated address is being used for commercial or residential purposes.
Note: This value will be no_data when Plaid does not have sufficient data to determine the address's use.

Possible values: residential, commercial, no_data
name
object
Result summary object specifying how the name field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
date_of_birth
object
Result summary object specifying how the date_of_birth field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
id_number
object
Result summary object specifying how the id_number field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
phone_number
object
Result summary object specifying how the phone field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
area_code
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
risk_check
nullableobject
Additional information for the risk_check step.
status
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
behavior
nullableobject
Result summary object specifying values for behavior attributes of risk check, when available.
user_interactions
string
Field describing the overall user interaction signals of a behavior risk check. This value represents how familiar the user is with the personal data they provide, based on a number of signals that are collected during their session.
genuine indicates the user has high familiarity with the data they are providing, and that fraud is unlikely.
neutral indicates some signals are present in between risky and genuine, but there are not enough clear signals to determine an outcome.
risky indicates the user has low familiarity with the data they are providing, and that fraud is likely.
no_data indicates there is not sufficient information to give an accurate signal.

Possible values: genuine, neutral, risky, no_data
fraud_ring_detected
string
Field describing the outcome of a fraud ring behavior risk check.
yes indicates that fraud ring activity was detected.
no indicates that fraud ring activity was not detected.
no_data indicates there was not enough information available to give an accurate signal.

Possible values: yes, no, no_data
bot_detected
string
Field describing the outcome of a bot detection behavior risk check.
yes indicates that automated activity was detected.
no indicates that automated activity was not detected.
no_data indicates there was not enough information available to give an accurate signal.

Possible values: yes, no, no_data
email
nullableobject
Result summary object specifying values for email attributes of risk check.
is_deliverable
string
SMTP-MX check to confirm the email address exists if known.

Possible values: yes, no, no_data
breach_count
nullableinteger
Count of all known breaches of this email address if known.
first_breached_at
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
last_breached_at
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
domain_registered_at
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
domain_is_free_provider
string
Indicates whether the email address domain is a free provider such as Gmail or Hotmail if known.

Possible values: yes, no, no_data
domain_is_custom
string
Indicates whether the email address domain is custom if known, i.e. a company domain and not free or disposable.

Possible values: yes, no, no_data
domain_is_disposable
string
Indicates whether the email domain is listed as disposable if known. Disposable domains are often used to create email addresses that are part of a fake set of user details.

Possible values: yes, no, no_data
top_level_domain_is_suspicious
string
Indicates whether the email address top level domain, which is the last part of the domain, is fraudulent or risky if known. In most cases, a suspicious top level domain is also associated with a disposable or high-risk domain.

Possible values: yes, no, no_data
linked_services
[string]
A list of online services where this email address has been detected to have accounts or other activity.

Possible values: apple, ebay, facebook, flickr, foursquare, github, google, gravatar, instagram, lastfm, linkedin, microsoft, myspace, pinterest, skype, spotify, telegram, tumblr, twitter, viber, vimeo, weibo, whatsapp, yahoo, airbnb, amazon, booking, discord, kakao, ok, qzone, line, snapchat, zalo
phone
nullableobject
Result summary object specifying values for phone attributes of risk check.
linked_services
[string]
A list of online services where this phone number has been detected to have accounts or other activity.

Possible values: apple, ebay, facebook, flickr, foursquare, github, google, gravatar, instagram, lastfm, linkedin, microsoft, myspace, pinterest, skype, spotify, telegram, tumblr, twitter, viber, vimeo, weibo, whatsapp, yahoo, airbnb, amazon, booking, discord, kakao, ok, qzone, line, snapchat, zalo
devices
[object]
Array of result summary objects specifying values for device attributes of risk check.
ip_proxy_type
nullablestring
An enum indicating whether a network proxy is present and if so what type it is.
none_detected indicates the user is not on a detectable proxy network.
tor indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network).
vpn indicates the user is on a VPN (Virtual Private Network)
web_proxy indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information.
public_proxy indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance.

Possible values: none_detected, tor, vpn, web_proxy, public_proxy
ip_spam_list_count
nullableinteger
Count of spam lists the IP address is associated with if known.
ip_timezone_offset
nullablestring
UTC offset of the timezone associated with the IP address.
identity_abuse_signals
nullableobject
Result summary object capturing abuse signals related to identity abuse, e.g. stolen and synthetic identity fraud.
synthetic_identity
nullableobject
Field containing the data used in determining the outcome of the synthetic identity risk check.
Contains the following fields:
score - A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.
score
integer
A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.
stolen_identity
nullableobject
Field containing the data used in determining the outcome of the stolen identity risk check.
Contains the following fields:
score - A score from 0 to 100 indicating the likelihood that the user is a stolen identity.
score
integer
A score from 0 to 100 indicating the likelihood that the user is a stolen identity.
watchlist_screening_id
nullablestring
ID of the associated screening.
redacted_at
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "idv_52xR9LKo77r1Np",
3  "client_user_id": "your-db-id-3b24110",
4  "created_at": "2020-07-24T03:26:02Z",
5  "completed_at": "2020-07-24T03:26:02Z",
6  "previous_attempt_id": "idv_42cF1MNo42r9Xj",
7  "shareable_url": "https://flow.plaid.com/verify/idv_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f",
8  "template": {
9    "id": "idvtmp_4FrXJvfQU3zGUR",
10    "version": 2
11  },
12  "user": {
13    "phone_number": "+19876543212",
14    "date_of_birth": "1990-05-29",
15    "ip_address": "192.0.2.42",
16    "email_address": "user@example.com",
17    "name": {
18      "given_name": "Leslie",
19      "family_name": "Knope"
20    },
21    "address": {
22      "street": "123 Main St.",
23      "street2": "Unit 42",
24      "city": "Pawnee",
25      "region": "IN",
26      "postal_code": "46001",
27      "country": "US"
28    },
29    "id_number": {
30      "value": "123456789",
31      "type": "us_ssn"
32    }
33  },
34  "status": "success",
35  "steps": {
36    "accept_tos": "success",
37    "verify_sms": "success",
38    "kyc_check": "success",
39    "documentary_verification": "success",
40    "selfie_check": "success",
41    "watchlist_screening": "success",
42    "risk_check": "success"
43  },
44  "documentary_verification": {
45    "status": "success",
46    "documents": [
47      {
48        "status": "success",
49        "attempt": 1,
50        "images": {
51          "original_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_front.jpeg",
52          "original_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_back.jpeg",
53          "cropped_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_front.jpeg",
54          "cropped_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_back.jpeg",
55          "face": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/face.jpeg"
56        },
57        "extracted_data": {
58          "id_number": "AB123456",
59          "category": "drivers_license",
60          "expiration_date": "1990-05-29",
61          "issuing_country": "US",
62          "issuing_region": "IN",
63          "date_of_birth": "1990-05-29",
64          "address": {
65            "street": "123 Main St. Unit 42",
66            "city": "Pawnee",
67            "region": "IN",
68            "postal_code": "46001",
69            "country": "US"
70          }
71        },
72        "analysis": {
73          "authenticity": "match",
74          "image_quality": "high",
75          "extracted_data": {
76            "name": "match",
77            "date_of_birth": "match",
78            "expiration_date": "not_expired",
79            "issuing_country": "match"
80          }
81        },
82        "redacted_at": "2020-07-24T03:26:02Z"
83      }
84    ]
85  },
86  "selfie_check": {
87    "status": "success",
88    "selfies": [
89      {
90        "status": "success",
91        "attempt": 1,
92        "capture": {
93          "image_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.jpeg",
94          "video_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.webm"
95        },
96        "analysis": {
97          "document_comparison": "match"
98        }
99      }
100    ]
101  },
102  "kyc_check": {
103    "status": "success",
104    "address": {
105      "summary": "match",
106      "po_box": "yes",
107      "type": "residential"
108    },
109    "name": {
110      "summary": "match"
111    },
112    "date_of_birth": {
113      "summary": "match"
114    },
115    "id_number": {
116      "summary": "match"
117    },
118    "phone_number": {
119      "summary": "match",
120      "area_code": "match"
121    }
122  },
123  "risk_check": {
124    "status": "success",
125    "behavior": {
126      "user_interactions": "risky",
127      "fraud_ring_detected": "yes",
128      "bot_detected": "yes"
129    },
130    "email": {
131      "is_deliverable": "yes",
132      "breach_count": 1,
133      "first_breached_at": "1990-05-29",
134      "last_breached_at": "1990-05-29",
135      "domain_registered_at": "1990-05-29",
136      "domain_is_free_provider": "yes",
137      "domain_is_custom": "yes",
138      "domain_is_disposable": "yes",
139      "top_level_domain_is_suspicious": "yes",
140      "linked_services": [
141        "apple"
142      ]
143    },
144    "phone": {
145      "linked_services": [
146        "apple"
147      ]
148    },
149    "devices": [
150      {
151        "ip_proxy_type": "none_detected",
152        "ip_spam_list_count": 1,
153        "ip_timezone_offset": "+06:00:00"
154      }
155    ],
156    "identity_abuse_signals": {
157      "synthetic_identity": {
158        "score": 0
159      },
160      "stolen_identity": {
161        "score": 0
162      }
163    }
164  },
165  "watchlist_screening_id": "scr_52xR9LKo77r1Np",
166  "redacted_at": "2020-07-24T03:26:02Z",
167  "request_id": "saKrIBuEB9qJZng"
168}
Was this helpful?

/identity_verification/get

Retrieve Identity Verification

Retrieve a previously created identity verification.

identity_verification/get

Request fields and example

identity_verification_id
requiredstring
ID of the associated Identity Verification attempt.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
Select Language
1const request: IdentityVerificationGetRequest = {
2  identity_verification_id: 'idv_52xR9LKo77r1Np',
3};
4try {
5  const response = await plaidClient.identityVerificationGet(request);
6} catch (error) {
7  // handle error
8}
identity_verification/get

Response fields and example

id
string
ID of the associated Identity Verification attempt.
client_user_id
string
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
completed_at
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
previous_attempt_id
nullablestring
The ID for the Identity Verification preceding this session. This field will only be filled if the current Identity Verification is a retry of a previous attempt.
shareable_url
nullablestring
A shareable URL that can be sent directly to the user to complete verification
template
object
The resource ID and version number of the template configuring the behavior of a given identity verification.
id
string
ID of the associated Identity Verification template.
version
integer
Version of the associated Identity Verification template.
user
object
The identity data that was either collected from the user or provided via API in order to perform an identity verification.
phone_number
nullablestring
A phone number in E.164 format.
date_of_birth
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
ip_address
nullablestring
An IPv4 or IPV6 address.
email_address
nullablestring
A valid email address.

Format: email
name
nullableobject
The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.
given_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
address
nullableobject
Even if an address has been collected, some fields may be null depending on the region's addressing system. For example:
Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include postal code
street
nullablestring
The primary street portion of an address. If the user has submitted their address, this field will always be filled.
street2
nullablestring
Extra street information, like an apartment or suite number.
city
nullablestring
City from the end user's address
region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
nullablestring
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
id_number
nullableobject
ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.
value
string
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
string
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
status
string
The status of this Identity Verification attempt.
active - The Identity Verification attempt is incomplete. The user may have completed part of the session, but has neither failed or passed.
success - The Identity Verification attempt has completed, passing all steps defined to the associated Identity Verification template
failed - The user failed one or more steps in the session and was told to contact support.
expired - The Identity Verification attempt was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future.
canceled - The Identity Verification attempt was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed.
pending_review - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review.

Possible values: active, success, failed, expired, canceled, pending_review
steps
object
Each step will be one of the following values:
active - This step is the user's current step. They are either in the process of completing this step, or they recently closed their Identity Verification attempt while in the middle of this step. Only one step will be marked as active at any given point.
success - The Identity Verification attempt has completed this step.
failed - The user failed this step. This can either call the user to fail the session as a whole, or cause them to fallback to another step depending on how the Identity Verification template is configured. A failed step does not imply a failed session.
waiting_for_prerequisite - The user needs to complete another step first, before they progress to this step. This step may never run, depending on if the user fails an earlier step or if the step is only run as a fallback.
not_applicable - This step will not be run for this session.
skipped - The retry instructions that created this Identity Verification attempt specified that this step should be skipped.
expired - This step had not yet been completed when the Identity Verification attempt as a whole expired.
canceled - The Identity Verification attempt was canceled before the user completed this step.
pending_review - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review.
manually_approved - The step was manually overridden to pass by a team member in the dashboard.
manually_rejected - The step was manually overridden to fail by a team member in the dashboard.
accept_tos
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
verify_sms
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
kyc_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
documentary_verification
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
selfie_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
watchlist_screening
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
risk_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
documentary_verification
nullableobject
Data, images, analysis, and results from the documentary_verification step. This field will be null unless steps.documentary_verification has reached a terminal state of either success or failed.
status
string
The outcome status for the associated Identity Verification attempt's documentary_verification step. This field will always have the same value as steps.documentary_verification.
documents
[object]
An array of documents submitted to the documentary_verification step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type.
Note: Plaid will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within documents. If the overall documentary_verification is failed, the user has exhausted their retry attempts.
status
string
An outcome status for this specific document submission. Distinct from the overall documentary_verification.status that summarizes the verification outcome from one or more documents.

Possible values: success, failed, manually_approved
attempt
integer
The attempt field begins with 1 and increments with each subsequent document upload.
images
object
URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the GET request for the associated Identity Verification attempt. A new expiring URL is generated with each request, so you can always rerequest the Identity Verification attempt if one of your URLs expires.
original_front
nullablestring
Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document.
original_back
nullablestring
Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected.
cropped_front
nullablestring
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document.
cropped_back
nullablestring
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected.
face
nullablestring
Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo.
extracted_data
nullableobject
Data extracted from a user-submitted document.
id_number
nullablestring
Alpha-numeric ID number extracted via OCR from the user's document image.
category
string
The type of identity document detected in the images provided. Will always be one of the following values:
drivers_license - A driver's license for the associated country
id_card - A general national identification card, distinct from driver's licenses
passport - A passport for the associated country
residence_permit_card - An identity document permitting a foreign citizen to temporarily reside in the associated country
resident_card - An identity document permitting a foreign citizen to permanently reside in the associated country
Note: This value may be different from the ID type that the user selects within Link. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say passport

Possible values: drivers_license, id_card, passport, residence_permit_card, resident_card
expiration_date
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
issuing_country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
issuing_region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
date_of_birth
nullablestring
A date extracted from the document in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
address
nullableobject
The address extracted from the document. The address must at least contain the following fields to be a valid address: street, city, country. If any are missing or unable to be extracted, the address will be null.
region, and postal_code may be null based on the addressing system. For example:
Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include postal code
Note: Optical Character Recognition (OCR) technology may sometimes extract incorrect data from a document.
street
string
The full street address extracted from the document.
city
string
City extracted from the document.
region
nullablestring
An ISO 3166-2 subdivision code extracted from the document. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
nullablestring
The postal code extracted from the document. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
string
Valid, capitalized, two-letter ISO code representing the country extracted from the document. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
analysis
object
High level descriptions of how the associated document was processed. If a document fails verification, the details in the analysis object should help clarify why the document was rejected.
authenticity
string
High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction.
For example, most identity documents have formatting rules like the following:
The image of the person's face must have a certain contrast in order to highlight skin tone
The subject in the document's image must remove eye glasses and pose in a certain way
The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules
Security features like watermarks and background patterns must be present
So a match status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document.

Possible values: match, partial_match, no_match, no_data
image_quality
string
A high level description of the quality of the image the user submitted.
For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks.
Note: By default, Plaid will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality.

Possible values: high, medium, low
extracted_data
nullableobject
Analysis of the data extracted from the submitted document.
name
string
A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to identity verification attempt.

Possible values: match, partial_match, no_match
date_of_birth
string
A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the identity verification attempt.

Possible values: match, partial_match, no_match
expiration_date
string
A description of whether the associated document was expired when the verification was performed.
Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be no_data.

Possible values: not_expired, expired, no_data
issuing_country
string
A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Plaid.
Note: You can configure whether a no_match on issuing_country fails the documentary_verification by editing your Plaid Template.

Possible values: match, no_match
redacted_at
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
selfie_check
nullableobject
Additional information for the selfie_check step. This field will be null unless steps.selfie_check has reached a terminal state of either success or failed.
status
string
The outcome status for the associated Identity Verification attempt's selfie_check step. This field will always have the same value as steps.selfie_check.

Possible values: success, failed
selfies
[object]
An array of selfies submitted to the selfie_check step. Each entry represents one user submission.
status
string
An outcome status for this specific selfie. Distinct from the overall selfie_check.status that summarizes the verification outcome from one or more selfies.

Possible values: success, failed
attempt
integer
The attempt field begins with 1 and increments with each subsequent selfie upload.
capture
object
The image or video capture of a selfie. Only one of image or video URL will be populated per selfie.
image_url
nullablestring
Temporary URL for downloading an image selfie capture.
video_url
nullablestring
Temporary URL for downloading a video selfie capture.
analysis
object
High level descriptions of how the associated selfie was processed. If a selfie fails verification, the details in the analysis object should help clarify why the selfie was rejected.
document_comparison
string
Information about the comparison between the selfie and the document (if documentary verification also ran).

Possible values: match, no_match, no_input
kyc_check
nullableobject
Additional information for the kyc_check step. This field will be null unless steps.kyc_check has reached a terminal state of either success or failed.
status
string
The outcome status for the associated Identity Verification attempt's kyc_check step. This field will always have the same value as steps.kyc_check.
address
object
Result summary object specifying how the address field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
po_box
string
Field describing whether the associated address is a post office box. Will be yes when a P.O. box is detected, no when Plaid confirmed the address is not a P.O. box, and no_data when Plaid was not able to determine if the address is a P.O. box.

Possible values: yes, no, no_data
type
string
Field describing whether the associated address is being used for commercial or residential purposes.
Note: This value will be no_data when Plaid does not have sufficient data to determine the address's use.

Possible values: residential, commercial, no_data
name
object
Result summary object specifying how the name field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
date_of_birth
object
Result summary object specifying how the date_of_birth field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
id_number
object
Result summary object specifying how the id_number field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
phone_number
object
Result summary object specifying how the phone field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
area_code
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
risk_check
nullableobject
Additional information for the risk_check step.
status
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
behavior
nullableobject
Result summary object specifying values for behavior attributes of risk check, when available.
user_interactions
string
Field describing the overall user interaction signals of a behavior risk check. This value represents how familiar the user is with the personal data they provide, based on a number of signals that are collected during their session.
genuine indicates the user has high familiarity with the data they are providing, and that fraud is unlikely.
neutral indicates some signals are present in between risky and genuine, but there are not enough clear signals to determine an outcome.
risky indicates the user has low familiarity with the data they are providing, and that fraud is likely.
no_data indicates there is not sufficient information to give an accurate signal.

Possible values: genuine, neutral, risky, no_data
fraud_ring_detected
string
Field describing the outcome of a fraud ring behavior risk check.
yes indicates that fraud ring activity was detected.
no indicates that fraud ring activity was not detected.
no_data indicates there was not enough information available to give an accurate signal.

Possible values: yes, no, no_data
bot_detected
string
Field describing the outcome of a bot detection behavior risk check.
yes indicates that automated activity was detected.
no indicates that automated activity was not detected.
no_data indicates there was not enough information available to give an accurate signal.

Possible values: yes, no, no_data
email
nullableobject
Result summary object specifying values for email attributes of risk check.
is_deliverable
string
SMTP-MX check to confirm the email address exists if known.

Possible values: yes, no, no_data
breach_count
nullableinteger
Count of all known breaches of this email address if known.
first_breached_at
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
last_breached_at
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
domain_registered_at
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
domain_is_free_provider
string
Indicates whether the email address domain is a free provider such as Gmail or Hotmail if known.

Possible values: yes, no, no_data
domain_is_custom
string
Indicates whether the email address domain is custom if known, i.e. a company domain and not free or disposable.

Possible values: yes, no, no_data
domain_is_disposable
string
Indicates whether the email domain is listed as disposable if known. Disposable domains are often used to create email addresses that are part of a fake set of user details.

Possible values: yes, no, no_data
top_level_domain_is_suspicious
string
Indicates whether the email address top level domain, which is the last part of the domain, is fraudulent or risky if known. In most cases, a suspicious top level domain is also associated with a disposable or high-risk domain.

Possible values: yes, no, no_data
linked_services
[string]
A list of online services where this email address has been detected to have accounts or other activity.

Possible values: apple, ebay, facebook, flickr, foursquare, github, google, gravatar, instagram, lastfm, linkedin, microsoft, myspace, pinterest, skype, spotify, telegram, tumblr, twitter, viber, vimeo, weibo, whatsapp, yahoo, airbnb, amazon, booking, discord, kakao, ok, qzone, line, snapchat, zalo
phone
nullableobject
Result summary object specifying values for phone attributes of risk check.
linked_services
[string]
A list of online services where this phone number has been detected to have accounts or other activity.

Possible values: apple, ebay, facebook, flickr, foursquare, github, google, gravatar, instagram, lastfm, linkedin, microsoft, myspace, pinterest, skype, spotify, telegram, tumblr, twitter, viber, vimeo, weibo, whatsapp, yahoo, airbnb, amazon, booking, discord, kakao, ok, qzone, line, snapchat, zalo
devices
[object]
Array of result summary objects specifying values for device attributes of risk check.
ip_proxy_type
nullablestring
An enum indicating whether a network proxy is present and if so what type it is.
none_detected indicates the user is not on a detectable proxy network.
tor indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network).
vpn indicates the user is on a VPN (Virtual Private Network)
web_proxy indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information.
public_proxy indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance.

Possible values: none_detected, tor, vpn, web_proxy, public_proxy
ip_spam_list_count
nullableinteger
Count of spam lists the IP address is associated with if known.
ip_timezone_offset
nullablestring
UTC offset of the timezone associated with the IP address.
identity_abuse_signals
nullableobject
Result summary object capturing abuse signals related to identity abuse, e.g. stolen and synthetic identity fraud.
synthetic_identity
nullableobject
Field containing the data used in determining the outcome of the synthetic identity risk check.
Contains the following fields:
score - A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.
score
integer
A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.
stolen_identity
nullableobject
Field containing the data used in determining the outcome of the stolen identity risk check.
Contains the following fields:
score - A score from 0 to 100 indicating the likelihood that the user is a stolen identity.
score
integer
A score from 0 to 100 indicating the likelihood that the user is a stolen identity.
watchlist_screening_id
nullablestring
ID of the associated screening.
redacted_at
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "idv_52xR9LKo77r1Np",
3  "client_user_id": "your-db-id-3b24110",
4  "created_at": "2020-07-24T03:26:02Z",
5  "completed_at": "2020-07-24T03:26:02Z",
6  "previous_attempt_id": "idv_42cF1MNo42r9Xj",
7  "shareable_url": "https://flow.plaid.com/verify/idv_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f",
8  "template": {
9    "id": "idvtmp_4FrXJvfQU3zGUR",
10    "version": 2
11  },
12  "user": {
13    "phone_number": "+19876543212",
14    "date_of_birth": "1990-05-29",
15    "ip_address": "192.0.2.42",
16    "email_address": "user@example.com",
17    "name": {
18      "given_name": "Leslie",
19      "family_name": "Knope"
20    },
21    "address": {
22      "street": "123 Main St.",
23      "street2": "Unit 42",
24      "city": "Pawnee",
25      "region": "IN",
26      "postal_code": "46001",
27      "country": "US"
28    },
29    "id_number": {
30      "value": "123456789",
31      "type": "us_ssn"
32    }
33  },
34  "status": "success",
35  "steps": {
36    "accept_tos": "success",
37    "verify_sms": "success",
38    "kyc_check": "success",
39    "documentary_verification": "success",
40    "selfie_check": "success",
41    "watchlist_screening": "success",
42    "risk_check": "success"
43  },
44  "documentary_verification": {
45    "status": "success",
46    "documents": [
47      {
48        "status": "success",
49        "attempt": 1,
50        "images": {
51          "original_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_front.jpeg",
52          "original_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_back.jpeg",
53          "cropped_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_front.jpeg",
54          "cropped_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_back.jpeg",
55          "face": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/face.jpeg"
56        },
57        "extracted_data": {
58          "id_number": "AB123456",
59          "category": "drivers_license",
60          "expiration_date": "1990-05-29",
61          "issuing_country": "US",
62          "issuing_region": "IN",
63          "date_of_birth": "1990-05-29",
64          "address": {
65            "street": "123 Main St. Unit 42",
66            "city": "Pawnee",
67            "region": "IN",
68            "postal_code": "46001",
69            "country": "US"
70          }
71        },
72        "analysis": {
73          "authenticity": "match",
74          "image_quality": "high",
75          "extracted_data": {
76            "name": "match",
77            "date_of_birth": "match",
78            "expiration_date": "not_expired",
79            "issuing_country": "match"
80          }
81        },
82        "redacted_at": "2020-07-24T03:26:02Z"
83      }
84    ]
85  },
86  "selfie_check": {
87    "status": "success",
88    "selfies": [
89      {
90        "status": "success",
91        "attempt": 1,
92        "capture": {
93          "image_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.jpeg",
94          "video_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.webm"
95        },
96        "analysis": {
97          "document_comparison": "match"
98        }
99      }
100    ]
101  },
102  "kyc_check": {
103    "status": "success",
104    "address": {
105      "summary": "match",
106      "po_box": "yes",
107      "type": "residential"
108    },
109    "name": {
110      "summary": "match"
111    },
112    "date_of_birth": {
113      "summary": "match"
114    },
115    "id_number": {
116      "summary": "match"
117    },
118    "phone_number": {
119      "summary": "match",
120      "area_code": "match"
121    }
122  },
123  "risk_check": {
124    "status": "success",
125    "behavior": {
126      "user_interactions": "risky",
127      "fraud_ring_detected": "yes",
128      "bot_detected": "yes"
129    },
130    "email": {
131      "is_deliverable": "yes",
132      "breach_count": 1,
133      "first_breached_at": "1990-05-29",
134      "last_breached_at": "1990-05-29",
135      "domain_registered_at": "1990-05-29",
136      "domain_is_free_provider": "yes",
137      "domain_is_custom": "yes",
138      "domain_is_disposable": "yes",
139      "top_level_domain_is_suspicious": "yes",
140      "linked_services": [
141        "apple"
142      ]
143    },
144    "phone": {
145      "linked_services": [
146        "apple"
147      ]
148    },
149    "devices": [
150      {
151        "ip_proxy_type": "none_detected",
152        "ip_spam_list_count": 1,
153        "ip_timezone_offset": "+06:00:00"
154      }
155    ],
156    "identity_abuse_signals": {
157      "synthetic_identity": {
158        "score": 0
159      },
160      "stolen_identity": {
161        "score": 0
162      }
163    }
164  },
165  "watchlist_screening_id": "scr_52xR9LKo77r1Np",
166  "redacted_at": "2020-07-24T03:26:02Z",
167  "request_id": "saKrIBuEB9qJZng"
168}
Was this helpful?

/identity_verification/list

List Identity Verifications

Filter and list Identity Verifications created by your account

identity_verification/list

Request fields and example

secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
template_id
requiredstring
ID of the associated Identity Verification template.
client_user_id
requiredstring
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
cursor
string
An identifier that determines which page of results you receive.
Select Language
1const request: ListIdentityVerificationRequest = {
2  template_id: 'idv_52xR9LKo77r1Np',
3  client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
4};
5try {
6  const response = await plaidClient.identityVerificationList(request);
7} catch (error) {
8  // handle error
9}
identity_verification/list

Response fields and example

identity_verifications
[object]
List of Plaid sessions
id
string
ID of the associated Identity Verification attempt.
client_user_id
string
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
completed_at
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
previous_attempt_id
nullablestring
The ID for the Identity Verification preceding this session. This field will only be filled if the current Identity Verification is a retry of a previous attempt.
shareable_url
nullablestring
A shareable URL that can be sent directly to the user to complete verification
template
object
The resource ID and version number of the template configuring the behavior of a given identity verification.
id
string
ID of the associated Identity Verification template.
version
integer
Version of the associated Identity Verification template.
user
object
The identity data that was either collected from the user or provided via API in order to perform an identity verification.
phone_number
nullablestring
A phone number in E.164 format.
date_of_birth
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
ip_address
nullablestring
An IPv4 or IPV6 address.
email_address
nullablestring
A valid email address.

Format: email
name
nullableobject
The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.
given_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
address
nullableobject
Even if an address has been collected, some fields may be null depending on the region's addressing system. For example:
Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include postal code
street
nullablestring
The primary street portion of an address. If the user has submitted their address, this field will always be filled.
street2
nullablestring
Extra street information, like an apartment or suite number.
city
nullablestring
City from the end user's address
region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
nullablestring
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
id_number
nullableobject
ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.
value
string
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
string
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
status
string
The status of this Identity Verification attempt.
active - The Identity Verification attempt is incomplete. The user may have completed part of the session, but has neither failed or passed.
success - The Identity Verification attempt has completed, passing all steps defined to the associated Identity Verification template
failed - The user failed one or more steps in the session and was told to contact support.
expired - The Identity Verification attempt was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future.
canceled - The Identity Verification attempt was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed.
pending_review - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review.

Possible values: active, success, failed, expired, canceled, pending_review
steps
object
Each step will be one of the following values:
active - This step is the user's current step. They are either in the process of completing this step, or they recently closed their Identity Verification attempt while in the middle of this step. Only one step will be marked as active at any given point.
success - The Identity Verification attempt has completed this step.
failed - The user failed this step. This can either call the user to fail the session as a whole, or cause them to fallback to another step depending on how the Identity Verification template is configured. A failed step does not imply a failed session.
waiting_for_prerequisite - The user needs to complete another step first, before they progress to this step. This step may never run, depending on if the user fails an earlier step or if the step is only run as a fallback.
not_applicable - This step will not be run for this session.
skipped - The retry instructions that created this Identity Verification attempt specified that this step should be skipped.
expired - This step had not yet been completed when the Identity Verification attempt as a whole expired.
canceled - The Identity Verification attempt was canceled before the user completed this step.
pending_review - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review.
manually_approved - The step was manually overridden to pass by a team member in the dashboard.
manually_rejected - The step was manually overridden to fail by a team member in the dashboard.
accept_tos
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
verify_sms
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
kyc_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
documentary_verification
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
selfie_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
watchlist_screening
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
risk_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
documentary_verification
nullableobject
Data, images, analysis, and results from the documentary_verification step. This field will be null unless steps.documentary_verification has reached a terminal state of either success or failed.
status
string
The outcome status for the associated Identity Verification attempt's documentary_verification step. This field will always have the same value as steps.documentary_verification.
documents
[object]
An array of documents submitted to the documentary_verification step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type.
Note: Plaid will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within documents. If the overall documentary_verification is failed, the user has exhausted their retry attempts.
status
string
An outcome status for this specific document submission. Distinct from the overall documentary_verification.status that summarizes the verification outcome from one or more documents.

Possible values: success, failed, manually_approved
attempt
integer
The attempt field begins with 1 and increments with each subsequent document upload.
images
object
URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the GET request for the associated Identity Verification attempt. A new expiring URL is generated with each request, so you can always rerequest the Identity Verification attempt if one of your URLs expires.
original_front
nullablestring
Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document.
original_back
nullablestring
Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected.
cropped_front
nullablestring
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document.
cropped_back
nullablestring
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected.
face
nullablestring
Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo.
extracted_data
nullableobject
Data extracted from a user-submitted document.
id_number
nullablestring
Alpha-numeric ID number extracted via OCR from the user's document image.
category
string
The type of identity document detected in the images provided. Will always be one of the following values:
drivers_license - A driver's license for the associated country
id_card - A general national identification card, distinct from driver's licenses
passport - A passport for the associated country
residence_permit_card - An identity document permitting a foreign citizen to temporarily reside in the associated country
resident_card - An identity document permitting a foreign citizen to permanently reside in the associated country
Note: This value may be different from the ID type that the user selects within Link. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say passport

Possible values: drivers_license, id_card, passport, residence_permit_card, resident_card
expiration_date
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
issuing_country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
issuing_region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
date_of_birth
nullablestring
A date extracted from the document in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
address
nullableobject
The address extracted from the document. The address must at least contain the following fields to be a valid address: street, city, country. If any are missing or unable to be extracted, the address will be null.
region, and postal_code may be null based on the addressing system. For example:
Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include postal code
Note: Optical Character Recognition (OCR) technology may sometimes extract incorrect data from a document.
street
string
The full street address extracted from the document.
city
string
City extracted from the document.
region
nullablestring
An ISO 3166-2 subdivision code extracted from the document. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
nullablestring
The postal code extracted from the document. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
string
Valid, capitalized, two-letter ISO code representing the country extracted from the document. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
analysis
object
High level descriptions of how the associated document was processed. If a document fails verification, the details in the analysis object should help clarify why the document was rejected.
authenticity
string
High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction.
For example, most identity documents have formatting rules like the following:
The image of the person's face must have a certain contrast in order to highlight skin tone
The subject in the document's image must remove eye glasses and pose in a certain way
The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules
Security features like watermarks and background patterns must be present
So a match status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document.

Possible values: match, partial_match, no_match, no_data
image_quality
string
A high level description of the quality of the image the user submitted.
For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks.
Note: By default, Plaid will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality.

Possible values: high, medium, low
extracted_data
nullableobject
Analysis of the data extracted from the submitted document.
name
string
A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to identity verification attempt.

Possible values: match, partial_match, no_match
date_of_birth
string
A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the identity verification attempt.

Possible values: match, partial_match, no_match
expiration_date
string
A description of whether the associated document was expired when the verification was performed.
Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be no_data.

Possible values: not_expired, expired, no_data
issuing_country
string
A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Plaid.
Note: You can configure whether a no_match on issuing_country fails the documentary_verification by editing your Plaid Template.

Possible values: match, no_match
redacted_at
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
selfie_check
nullableobject
Additional information for the selfie_check step. This field will be null unless steps.selfie_check has reached a terminal state of either success or failed.
status
string
The outcome status for the associated Identity Verification attempt's selfie_check step. This field will always have the same value as steps.selfie_check.

Possible values: success, failed
selfies
[object]
An array of selfies submitted to the selfie_check step. Each entry represents one user submission.
status
string
An outcome status for this specific selfie. Distinct from the overall selfie_check.status that summarizes the verification outcome from one or more selfies.

Possible values: success, failed
attempt
integer
The attempt field begins with 1 and increments with each subsequent selfie upload.
capture
object
The image or video capture of a selfie. Only one of image or video URL will be populated per selfie.
image_url
nullablestring
Temporary URL for downloading an image selfie capture.
video_url
nullablestring
Temporary URL for downloading a video selfie capture.
analysis
object
High level descriptions of how the associated selfie was processed. If a selfie fails verification, the details in the analysis object should help clarify why the selfie was rejected.
document_comparison
string
Information about the comparison between the selfie and the document (if documentary verification also ran).

Possible values: match, no_match, no_input
kyc_check
nullableobject
Additional information for the kyc_check step. This field will be null unless steps.kyc_check has reached a terminal state of either success or failed.
status
string
The outcome status for the associated Identity Verification attempt's kyc_check step. This field will always have the same value as steps.kyc_check.
address
object
Result summary object specifying how the address field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
po_box
string
Field describing whether the associated address is a post office box. Will be yes when a P.O. box is detected, no when Plaid confirmed the address is not a P.O. box, and no_data when Plaid was not able to determine if the address is a P.O. box.

Possible values: yes, no, no_data
type
string
Field describing whether the associated address is being used for commercial or residential purposes.
Note: This value will be no_data when Plaid does not have sufficient data to determine the address's use.

Possible values: residential, commercial, no_data
name
object
Result summary object specifying how the name field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
date_of_birth
object
Result summary object specifying how the date_of_birth field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
id_number
object
Result summary object specifying how the id_number field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
phone_number
object
Result summary object specifying how the phone field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
area_code
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
risk_check
nullableobject
Additional information for the risk_check step.
status
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
behavior
nullableobject
Result summary object specifying values for behavior attributes of risk check, when available.
user_interactions
string
Field describing the overall user interaction signals of a behavior risk check. This value represents how familiar the user is with the personal data they provide, based on a number of signals that are collected during their session.
genuine indicates the user has high familiarity with the data they are providing, and that fraud is unlikely.
neutral indicates some signals are present in between risky and genuine, but there are not enough clear signals to determine an outcome.
risky indicates the user has low familiarity with the data they are providing, and that fraud is likely.
no_data indicates there is not sufficient information to give an accurate signal.

Possible values: genuine, neutral, risky, no_data
fraud_ring_detected
string
Field describing the outcome of a fraud ring behavior risk check.
yes indicates that fraud ring activity was detected.
no indicates that fraud ring activity was not detected.
no_data indicates there was not enough information available to give an accurate signal.

Possible values: yes, no, no_data
bot_detected
string
Field describing the outcome of a bot detection behavior risk check.
yes indicates that automated activity was detected.
no indicates that automated activity was not detected.
no_data indicates there was not enough information available to give an accurate signal.

Possible values: yes, no, no_data
email
nullableobject
Result summary object specifying values for email attributes of risk check.
is_deliverable
string
SMTP-MX check to confirm the email address exists if known.

Possible values: yes, no, no_data
breach_count
nullableinteger
Count of all known breaches of this email address if known.
first_breached_at
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
last_breached_at
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
domain_registered_at
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
domain_is_free_provider
string
Indicates whether the email address domain is a free provider such as Gmail or Hotmail if known.

Possible values: yes, no, no_data
domain_is_custom
string
Indicates whether the email address domain is custom if known, i.e. a company domain and not free or disposable.

Possible values: yes, no, no_data
domain_is_disposable
string
Indicates whether the email domain is listed as disposable if known. Disposable domains are often used to create email addresses that are part of a fake set of user details.

Possible values: yes, no, no_data
top_level_domain_is_suspicious
string
Indicates whether the email address top level domain, which is the last part of the domain, is fraudulent or risky if known. In most cases, a suspicious top level domain is also associated with a disposable or high-risk domain.

Possible values: yes, no, no_data
linked_services
[string]
A list of online services where this email address has been detected to have accounts or other activity.

Possible values: apple, ebay, facebook, flickr, foursquare, github, google, gravatar, instagram, lastfm, linkedin, microsoft, myspace, pinterest, skype, spotify, telegram, tumblr, twitter, viber, vimeo, weibo, whatsapp, yahoo, airbnb, amazon, booking, discord, kakao, ok, qzone, line, snapchat, zalo
phone
nullableobject
Result summary object specifying values for phone attributes of risk check.
linked_services
[string]
A list of online services where this phone number has been detected to have accounts or other activity.

Possible values: apple, ebay, facebook, flickr, foursquare, github, google, gravatar, instagram, lastfm, linkedin, microsoft, myspace, pinterest, skype, spotify, telegram, tumblr, twitter, viber, vimeo, weibo, whatsapp, yahoo, airbnb, amazon, booking, discord, kakao, ok, qzone, line, snapchat, zalo
devices
[object]
Array of result summary objects specifying values for device attributes of risk check.
ip_proxy_type
nullablestring
An enum indicating whether a network proxy is present and if so what type it is.
none_detected indicates the user is not on a detectable proxy network.
tor indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network).
vpn indicates the user is on a VPN (Virtual Private Network)
web_proxy indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information.
public_proxy indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance.

Possible values: none_detected, tor, vpn, web_proxy, public_proxy
ip_spam_list_count
nullableinteger
Count of spam lists the IP address is associated with if known.
ip_timezone_offset
nullablestring
UTC offset of the timezone associated with the IP address.
identity_abuse_signals
nullableobject
Result summary object capturing abuse signals related to identity abuse, e.g. stolen and synthetic identity fraud.
synthetic_identity
nullableobject
Field containing the data used in determining the outcome of the synthetic identity risk check.
Contains the following fields:
score - A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.
score
integer
A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.
stolen_identity
nullableobject
Field containing the data used in determining the outcome of the stolen identity risk check.
Contains the following fields:
score - A score from 0 to 100 indicating the likelihood that the user is a stolen identity.
score
integer
A score from 0 to 100 indicating the likelihood that the user is a stolen identity.
watchlist_screening_id
nullablestring
ID of the associated screening.
redacted_at
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
next_cursor
nullablestring
An identifier that determines which page of results you receive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "identity_verifications": [
3    {
4      "id": "idv_52xR9LKo77r1Np",
5      "client_user_id": "your-db-id-3b24110",
6      "created_at": "2020-07-24T03:26:02Z",
7      "completed_at": "2020-07-24T03:26:02Z",
8      "previous_attempt_id": "idv_42cF1MNo42r9Xj",
9      "shareable_url": "https://flow.plaid.com/verify/idv_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f",
10      "template": {
11        "id": "idvtmp_4FrXJvfQU3zGUR",
12        "version": 2
13      },
14      "user": {
15        "phone_number": "+19876543212",
16        "date_of_birth": "1990-05-29",
17        "ip_address": "192.0.2.42",
18        "email_address": "user@example.com",
19        "name": {
20          "given_name": "Leslie",
21          "family_name": "Knope"
22        },
23        "address": {
24          "street": "123 Main St.",
25          "street2": "Unit 42",
26          "city": "Pawnee",
27          "region": "IN",
28          "postal_code": "46001",
29          "country": "US"
30        },
31        "id_number": {
32          "value": "123456789",
33          "type": "us_ssn"
34        }
35      },
36      "status": "success",
37      "steps": {
38        "accept_tos": "success",
39        "verify_sms": "success",
40        "kyc_check": "success",
41        "documentary_verification": "success",
42        "selfie_check": "success",
43        "watchlist_screening": "success",
44        "risk_check": "success"
45      },
46      "documentary_verification": {
47        "status": "success",
48        "documents": [
49          {
50            "status": "success",
51            "attempt": 1,
52            "images": {
53              "original_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_front.jpeg",
54              "original_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_back.jpeg",
55              "cropped_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_front.jpeg",
56              "cropped_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_back.jpeg",
57              "face": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/face.jpeg"
58            },
59            "extracted_data": {
60              "id_number": "AB123456",
61              "category": "drivers_license",
62              "expiration_date": "1990-05-29",
63              "issuing_country": "US",
64              "issuing_region": "IN",
65              "date_of_birth": "1990-05-29",
66              "address": {
67                "street": "123 Main St. Unit 42",
68                "city": "Pawnee",
69                "region": "IN",
70                "postal_code": "46001",
71                "country": "US"
72              }
73            },
74            "analysis": {
75              "authenticity": "match",
76              "image_quality": "high",
77              "extracted_data": {
78                "name": "match",
79                "date_of_birth": "match",
80                "expiration_date": "not_expired",
81                "issuing_country": "match"
82              }
83            },
84            "redacted_at": "2020-07-24T03:26:02Z"
85          }
86        ]
87      },
88      "selfie_check": {
89        "status": "success",
90        "selfies": [
91          {
92            "status": "success",
93            "attempt": 1,
94            "capture": {
95              "image_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.jpeg",
96              "video_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.webm"
97            },
98            "analysis": {
99              "document_comparison": "match"
100            }
101          }
102        ]
103      },
104      "kyc_check": {
105        "status": "success",
106        "address": {
107          "summary": "match",
108          "po_box": "yes",
109          "type": "residential"
110        },
111        "name": {
112          "summary": "match"
113        },
114        "date_of_birth": {
115          "summary": "match"
116        },
117        "id_number": {
118          "summary": "match"
119        },
120        "phone_number": {
121          "summary": "match",
122          "area_code": "match"
123        }
124      },
125      "risk_check": {
126        "status": "success",
127        "behavior": {
128          "user_interactions": "risky",
129          "fraud_ring_detected": "yes",
130          "bot_detected": "yes"
131        },
132        "email": {
133          "is_deliverable": "yes",
134          "breach_count": 1,
135          "first_breached_at": "1990-05-29",
136          "last_breached_at": "1990-05-29",
137          "domain_registered_at": "1990-05-29",
138          "domain_is_free_provider": "yes",
139          "domain_is_custom": "yes",
140          "domain_is_disposable": "yes",
141          "top_level_domain_is_suspicious": "yes",
142          "linked_services": [
143            "apple"
144          ]
145        },
146        "phone": {
147          "linked_services": [
148            "apple"
149          ]
150        },
151        "devices": [
152          {
153            "ip_proxy_type": "none_detected",
154            "ip_spam_list_count": 1,
155            "ip_timezone_offset": "+06:00:00"
156          }
157        ],
158        "identity_abuse_signals": {
159          "synthetic_identity": {
160            "score": 0
161          },
162          "stolen_identity": {
163            "score": 0
164          }
165        }
166      },
167      "watchlist_screening_id": "scr_52xR9LKo77r1Np",
168      "redacted_at": "2020-07-24T03:26:02Z"
169    }
170  ],
171  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
172  "request_id": "saKrIBuEB9qJZng"
173}
Was this helpful?

/identity_verification/retry

Retry an Identity Verification

Allow a customer to retry their identity verification

identity_verification/retry

Request fields and example

client_user_id
requiredstring
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
template_id
requiredstring
ID of the associated Identity Verification template.
strategy
requiredstring
An instruction specifying what steps the new Identity Verification attempt should require the user to complete:
reset - Restart the user at the beginning of the session, regardless of whether they successfully completed part of their previous session.
incomplete - Start the new session at the step that the user failed in the previous session, skipping steps that have already been successfully completed.
infer - If the most recent Identity Verification attempt associated with the given client_user_id has a status of failed or expired, retry using the incomplete strategy. Otherwise, use the reset strategy.
custom - Start the new session with a custom configuration, specified by the value of the steps field
Note:
The incomplete strategy cannot be applied if the session's failing step is screening or risk_check.
The infer strategy cannot be applied if the session's status is still active

Possible values: reset, incomplete, infer, custom
user
object
User information collected outside of Link, most likely via your own onboarding process.
Each of the following identity fields are optional:
email_address
phone_number
date_of_birth
name
address
id_number
Specifically, these fields are optional in that they can either be fully provided (satisfying every required field in their subschema) or omitted from the request entirely by not providing the key or value. Providing these fields via the API will result in Link skipping the data collection process for the associated user. All verification steps enabled in the associated Identity Verification Template will still be run. Verification steps will either be run immediately, or once the user completes the accept_tos step, depending on the value provided to the gave_consent field.
email_address
string
A valid email address.

Format: email
phone_number
string
A phone number in E.164 format.
date_of_birth
string
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
name
object
You can use this field to pre-populate the user's legal name; if it is provided here, they will not be prompted to enter their name in the identity verification attempt.
given_name
requiredstring
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
requiredstring
A string with at least one non-whitespace character, with a max length of 100 characters.
address
object
Home address for the user. For more context on this field, see Input Validation by Country.
street
requiredstring
The primary street portion of an address. If the user has submitted their address, this field will always be filled.
street2
string
Extra street information, like an apartment or suite number.
city
requiredstring
City from the end user's address
region
string
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
string
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
requiredstring
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
id_number
object
ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.
value
requiredstring
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
requiredstring
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
steps
object
Instructions for the custom retry strategy specifying which steps should be required or skipped.
Note:
This field must be provided when the retry strategy is custom and must be omitted otherwise.
Custom retries override settings in your Plaid Template. For example, if your Plaid Template has verify_sms disabled, a custom retry with verify_sms enabled will still require the step.
The selfie_check step is currently not supported on the sandbox server. Sandbox requests will silently disable the selfie_check step when provided.
verify_sms
requiredboolean
A boolean field specifying whether the new session should require or skip the verify_sms step.
kyc_check
requiredboolean
A boolean field specifying whether the new session should require or skip the kyc_check step.
documentary_verification
requiredboolean
A boolean field specifying whether the new session should require or skip the documentary_verification step.
selfie_check
requiredboolean
A boolean field specifying whether the new session should require or skip the selfie_check step.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
Select Language
1const request: IdentityVerificationRetryRequest = {
2  client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3  template_id: 'idv_52xR9LKo77r1Np',
4  strategy: 'reset',
5  user: {
6    email_address: 'acharleston@email.com',
7    phone_number: '+11234567890',
8    date_of_birth: '1975-01-18',
9    name: {
10      given_name: 'Anna',
11      family_name: 'Charleston',
12    },
13    address: {
14      street: '100 Market Street',
15      street2: 'Apt 1A',
16      city: 'San Francisco',
17      region: 'CA',
18      postal_code: '94103',
19      country: 'US',
20    },
21    id_number: {
22      value: '123456789',
23      type: 'us_ssn',
24    },
25  },
26};
27try {
28  const response = await plaidClient.identityVerificationRetry(request);
29} catch (error) {
30  // handle error
31}
identity_verification/retry

Response fields and example

id
string
ID of the associated Identity Verification attempt.
client_user_id
string
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
completed_at
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
previous_attempt_id
nullablestring
The ID for the Identity Verification preceding this session. This field will only be filled if the current Identity Verification is a retry of a previous attempt.
shareable_url
nullablestring
A shareable URL that can be sent directly to the user to complete verification
template
object
The resource ID and version number of the template configuring the behavior of a given identity verification.
id
string
ID of the associated Identity Verification template.
version
integer
Version of the associated Identity Verification template.
user
object
The identity data that was either collected from the user or provided via API in order to perform an identity verification.
phone_number
nullablestring
A phone number in E.164 format.
date_of_birth
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
ip_address
nullablestring
An IPv4 or IPV6 address.
email_address
nullablestring
A valid email address.

Format: email
name
nullableobject
The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.
given_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
address
nullableobject
Even if an address has been collected, some fields may be null depending on the region's addressing system. For example:
Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include postal code
street
nullablestring
The primary street portion of an address. If the user has submitted their address, this field will always be filled.
street2
nullablestring
Extra street information, like an apartment or suite number.
city
nullablestring
City from the end user's address
region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
nullablestring
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
id_number
nullableobject
ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.
value
string
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
string
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
status
string
The status of this Identity Verification attempt.
active - The Identity Verification attempt is incomplete. The user may have completed part of the session, but has neither failed or passed.
success - The Identity Verification attempt has completed, passing all steps defined to the associated Identity Verification template
failed - The user failed one or more steps in the session and was told to contact support.
expired - The Identity Verification attempt was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future.
canceled - The Identity Verification attempt was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed.
pending_review - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review.

Possible values: active, success, failed, expired, canceled, pending_review
steps
object
Each step will be one of the following values:
active - This step is the user's current step. They are either in the process of completing this step, or they recently closed their Identity Verification attempt while in the middle of this step. Only one step will be marked as active at any given point.
success - The Identity Verification attempt has completed this step.
failed - The user failed this step. This can either call the user to fail the session as a whole, or cause them to fallback to another step depending on how the Identity Verification template is configured. A failed step does not imply a failed session.
waiting_for_prerequisite - The user needs to complete another step first, before they progress to this step. This step may never run, depending on if the user fails an earlier step or if the step is only run as a fallback.
not_applicable - This step will not be run for this session.
skipped - The retry instructions that created this Identity Verification attempt specified that this step should be skipped.
expired - This step had not yet been completed when the Identity Verification attempt as a whole expired.
canceled - The Identity Verification attempt was canceled before the user completed this step.
pending_review - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review.
manually_approved - The step was manually overridden to pass by a team member in the dashboard.
manually_rejected - The step was manually overridden to fail by a team member in the dashboard.
accept_tos
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
verify_sms
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
kyc_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
documentary_verification
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
selfie_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
watchlist_screening
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
risk_check
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
documentary_verification
nullableobject
Data, images, analysis, and results from the documentary_verification step. This field will be null unless steps.documentary_verification has reached a terminal state of either success or failed.
status
string
The outcome status for the associated Identity Verification attempt's documentary_verification step. This field will always have the same value as steps.documentary_verification.
documents
[object]
An array of documents submitted to the documentary_verification step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type.
Note: Plaid will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within documents. If the overall documentary_verification is failed, the user has exhausted their retry attempts.
status
string
An outcome status for this specific document submission. Distinct from the overall documentary_verification.status that summarizes the verification outcome from one or more documents.

Possible values: success, failed, manually_approved
attempt
integer
The attempt field begins with 1 and increments with each subsequent document upload.
images
object
URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the GET request for the associated Identity Verification attempt. A new expiring URL is generated with each request, so you can always rerequest the Identity Verification attempt if one of your URLs expires.
original_front
nullablestring
Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document.
original_back
nullablestring
Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected.
cropped_front
nullablestring
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document.
cropped_back
nullablestring
Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected.
face
nullablestring
Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo.
extracted_data
nullableobject
Data extracted from a user-submitted document.
id_number
nullablestring
Alpha-numeric ID number extracted via OCR from the user's document image.
category
string
The type of identity document detected in the images provided. Will always be one of the following values:
drivers_license - A driver's license for the associated country
id_card - A general national identification card, distinct from driver's licenses
passport - A passport for the associated country
residence_permit_card - An identity document permitting a foreign citizen to temporarily reside in the associated country
resident_card - An identity document permitting a foreign citizen to permanently reside in the associated country
Note: This value may be different from the ID type that the user selects within Link. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say passport

Possible values: drivers_license, id_card, passport, residence_permit_card, resident_card
expiration_date
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
issuing_country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
issuing_region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
date_of_birth
nullablestring
A date extracted from the document in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
address
nullableobject
The address extracted from the document. The address must at least contain the following fields to be a valid address: street, city, country. If any are missing or unable to be extracted, the address will be null.
region, and postal_code may be null based on the addressing system. For example:
Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include postal code
Note: Optical Character Recognition (OCR) technology may sometimes extract incorrect data from a document.
street
string
The full street address extracted from the document.
city
string
City extracted from the document.
region
nullablestring
An ISO 3166-2 subdivision code extracted from the document. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
nullablestring
The postal code extracted from the document. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
string
Valid, capitalized, two-letter ISO code representing the country extracted from the document. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
analysis
object
High level descriptions of how the associated document was processed. If a document fails verification, the details in the analysis object should help clarify why the document was rejected.
authenticity
string
High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction.
For example, most identity documents have formatting rules like the following:
The image of the person's face must have a certain contrast in order to highlight skin tone
The subject in the document's image must remove eye glasses and pose in a certain way
The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules
Security features like watermarks and background patterns must be present
So a match status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document.

Possible values: match, partial_match, no_match, no_data
image_quality
string
A high level description of the quality of the image the user submitted.
For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks.
Note: By default, Plaid will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality.

Possible values: high, medium, low
extracted_data
nullableobject
Analysis of the data extracted from the submitted document.
name
string
A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to identity verification attempt.

Possible values: match, partial_match, no_match
date_of_birth
string
A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the identity verification attempt.

Possible values: match, partial_match, no_match
expiration_date
string
A description of whether the associated document was expired when the verification was performed.
Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be no_data.

Possible values: not_expired, expired, no_data
issuing_country
string
A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Plaid.
Note: You can configure whether a no_match on issuing_country fails the documentary_verification by editing your Plaid Template.

Possible values: match, no_match
redacted_at
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
selfie_check
nullableobject
Additional information for the selfie_check step. This field will be null unless steps.selfie_check has reached a terminal state of either success or failed.
status
string
The outcome status for the associated Identity Verification attempt's selfie_check step. This field will always have the same value as steps.selfie_check.

Possible values: success, failed
selfies
[object]
An array of selfies submitted to the selfie_check step. Each entry represents one user submission.
status
string
An outcome status for this specific selfie. Distinct from the overall selfie_check.status that summarizes the verification outcome from one or more selfies.

Possible values: success, failed
attempt
integer
The attempt field begins with 1 and increments with each subsequent selfie upload.
capture
object
The image or video capture of a selfie. Only one of image or video URL will be populated per selfie.
image_url
nullablestring
Temporary URL for downloading an image selfie capture.
video_url
nullablestring
Temporary URL for downloading a video selfie capture.
analysis
object
High level descriptions of how the associated selfie was processed. If a selfie fails verification, the details in the analysis object should help clarify why the selfie was rejected.
document_comparison
string
Information about the comparison between the selfie and the document (if documentary verification also ran).

Possible values: match, no_match, no_input
kyc_check
nullableobject
Additional information for the kyc_check step. This field will be null unless steps.kyc_check has reached a terminal state of either success or failed.
status
string
The outcome status for the associated Identity Verification attempt's kyc_check step. This field will always have the same value as steps.kyc_check.
address
object
Result summary object specifying how the address field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
po_box
string
Field describing whether the associated address is a post office box. Will be yes when a P.O. box is detected, no when Plaid confirmed the address is not a P.O. box, and no_data when Plaid was not able to determine if the address is a P.O. box.

Possible values: yes, no, no_data
type
string
Field describing whether the associated address is being used for commercial or residential purposes.
Note: This value will be no_data when Plaid does not have sufficient data to determine the address's use.

Possible values: residential, commercial, no_data
name
object
Result summary object specifying how the name field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
date_of_birth
object
Result summary object specifying how the date_of_birth field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
id_number
object
Result summary object specifying how the id_number field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
phone_number
object
Result summary object specifying how the phone field matched.
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
area_code
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
risk_check
nullableobject
Additional information for the risk_check step.
status
string
The status of a step in the identity verification process.

Possible values: success, active, failed, waiting_for_prerequisite, not_applicable, skipped, expired, canceled, pending_review, manually_approved, manually_rejected
behavior
nullableobject
Result summary object specifying values for behavior attributes of risk check, when available.
user_interactions
string
Field describing the overall user interaction signals of a behavior risk check. This value represents how familiar the user is with the personal data they provide, based on a number of signals that are collected during their session.
genuine indicates the user has high familiarity with the data they are providing, and that fraud is unlikely.
neutral indicates some signals are present in between risky and genuine, but there are not enough clear signals to determine an outcome.
risky indicates the user has low familiarity with the data they are providing, and that fraud is likely.
no_data indicates there is not sufficient information to give an accurate signal.

Possible values: genuine, neutral, risky, no_data
fraud_ring_detected
string
Field describing the outcome of a fraud ring behavior risk check.
yes indicates that fraud ring activity was detected.
no indicates that fraud ring activity was not detected.
no_data indicates there was not enough information available to give an accurate signal.

Possible values: yes, no, no_data
bot_detected
string
Field describing the outcome of a bot detection behavior risk check.
yes indicates that automated activity was detected.
no indicates that automated activity was not detected.
no_data indicates there was not enough information available to give an accurate signal.

Possible values: yes, no, no_data
email
nullableobject
Result summary object specifying values for email attributes of risk check.
is_deliverable
string
SMTP-MX check to confirm the email address exists if known.

Possible values: yes, no, no_data
breach_count
nullableinteger
Count of all known breaches of this email address if known.
first_breached_at
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
last_breached_at
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
domain_registered_at
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
domain_is_free_provider
string
Indicates whether the email address domain is a free provider such as Gmail or Hotmail if known.

Possible values: yes, no, no_data
domain_is_custom
string
Indicates whether the email address domain is custom if known, i.e. a company domain and not free or disposable.

Possible values: yes, no, no_data
domain_is_disposable
string
Indicates whether the email domain is listed as disposable if known. Disposable domains are often used to create email addresses that are part of a fake set of user details.

Possible values: yes, no, no_data
top_level_domain_is_suspicious
string
Indicates whether the email address top level domain, which is the last part of the domain, is fraudulent or risky if known. In most cases, a suspicious top level domain is also associated with a disposable or high-risk domain.

Possible values: yes, no, no_data
linked_services
[string]
A list of online services where this email address has been detected to have accounts or other activity.

Possible values: apple, ebay, facebook, flickr, foursquare, github, google, gravatar, instagram, lastfm, linkedin, microsoft, myspace, pinterest, skype, spotify, telegram, tumblr, twitter, viber, vimeo, weibo, whatsapp, yahoo, airbnb, amazon, booking, discord, kakao, ok, qzone, line, snapchat, zalo
phone
nullableobject
Result summary object specifying values for phone attributes of risk check.
linked_services
[string]
A list of online services where this phone number has been detected to have accounts or other activity.

Possible values: apple, ebay, facebook, flickr, foursquare, github, google, gravatar, instagram, lastfm, linkedin, microsoft, myspace, pinterest, skype, spotify, telegram, tumblr, twitter, viber, vimeo, weibo, whatsapp, yahoo, airbnb, amazon, booking, discord, kakao, ok, qzone, line, snapchat, zalo
devices
[object]
Array of result summary objects specifying values for device attributes of risk check.
ip_proxy_type
nullablestring
An enum indicating whether a network proxy is present and if so what type it is.
none_detected indicates the user is not on a detectable proxy network.
tor indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network).
vpn indicates the user is on a VPN (Virtual Private Network)
web_proxy indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information.
public_proxy indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance.

Possible values: none_detected, tor, vpn, web_proxy, public_proxy
ip_spam_list_count
nullableinteger
Count of spam lists the IP address is associated with if known.
ip_timezone_offset
nullablestring
UTC offset of the timezone associated with the IP address.
identity_abuse_signals
nullableobject
Result summary object capturing abuse signals related to identity abuse, e.g. stolen and synthetic identity fraud.
synthetic_identity
nullableobject
Field containing the data used in determining the outcome of the synthetic identity risk check.
Contains the following fields:
score - A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.
score
integer
A score from 0 to 100 indicating the likelihood that the user is a synthetic identity.
stolen_identity
nullableobject
Field containing the data used in determining the outcome of the stolen identity risk check.
Contains the following fields:
score - A score from 0 to 100 indicating the likelihood that the user is a stolen identity.
score
integer
A score from 0 to 100 indicating the likelihood that the user is a stolen identity.
watchlist_screening_id
nullablestring
ID of the associated screening.
redacted_at
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "idv_52xR9LKo77r1Np",
3  "client_user_id": "your-db-id-3b24110",
4  "created_at": "2020-07-24T03:26:02Z",
5  "completed_at": "2020-07-24T03:26:02Z",
6  "previous_attempt_id": "idv_42cF1MNo42r9Xj",
7  "shareable_url": "https://flow.plaid.com/verify/idv_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f",
8  "template": {
9    "id": "idvtmp_4FrXJvfQU3zGUR",
10    "version": 2
11  },
12  "user": {
13    "phone_number": "+19876543212",
14    "date_of_birth": "1990-05-29",
15    "ip_address": "192.0.2.42",
16    "email_address": "user@example.com",
17    "name": {
18      "given_name": "Leslie",
19      "family_name": "Knope"
20    },
21    "address": {
22      "street": "123 Main St.",
23      "street2": "Unit 42",
24      "city": "Pawnee",
25      "region": "IN",
26      "postal_code": "46001",
27      "country": "US"
28    },
29    "id_number": {
30      "value": "123456789",
31      "type": "us_ssn"
32    }
33  },
34  "status": "success",
35  "steps": {
36    "accept_tos": "success",
37    "verify_sms": "success",
38    "kyc_check": "success",
39    "documentary_verification": "success",
40    "selfie_check": "success",
41    "watchlist_screening": "success",
42    "risk_check": "success"
43  },
44  "documentary_verification": {
45    "status": "success",
46    "documents": [
47      {
48        "status": "success",
49        "attempt": 1,
50        "images": {
51          "original_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_front.jpeg",
52          "original_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_back.jpeg",
53          "cropped_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_front.jpeg",
54          "cropped_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_back.jpeg",
55          "face": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/face.jpeg"
56        },
57        "extracted_data": {
58          "id_number": "AB123456",
59          "category": "drivers_license",
60          "expiration_date": "1990-05-29",
61          "issuing_country": "US",
62          "issuing_region": "IN",
63          "date_of_birth": "1990-05-29",
64          "address": {
65            "street": "123 Main St. Unit 42",
66            "city": "Pawnee",
67            "region": "IN",
68            "postal_code": "46001",
69            "country": "US"
70          }
71        },
72        "analysis": {
73          "authenticity": "match",
74          "image_quality": "high",
75          "extracted_data": {
76            "name": "match",
77            "date_of_birth": "match",
78            "expiration_date": "not_expired",
79            "issuing_country": "match"
80          }
81        },
82        "redacted_at": "2020-07-24T03:26:02Z"
83      }
84    ]
85  },
86  "selfie_check": {
87    "status": "success",
88    "selfies": [
89      {
90        "status": "success",
91        "attempt": 1,
92        "capture": {
93          "image_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.jpeg",
94          "video_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.webm"
95        },
96        "analysis": {
97          "document_comparison": "match"
98        }
99      }
100    ]
101  },
102  "kyc_check": {
103    "status": "success",
104    "address": {
105      "summary": "match",
106      "po_box": "yes",
107      "type": "residential"
108    },
109    "name": {
110      "summary": "match"
111    },
112    "date_of_birth": {
113      "summary": "match"
114    },
115    "id_number": {
116      "summary": "match"
117    },
118    "phone_number": {
119      "summary": "match",
120      "area_code": "match"
121    }
122  },
123  "risk_check": {
124    "status": "success",
125    "behavior": {
126      "user_interactions": "risky",
127      "fraud_ring_detected": "yes",
128      "bot_detected": "yes"
129    },
130    "email": {
131      "is_deliverable": "yes",
132      "breach_count": 1,
133      "first_breached_at": "1990-05-29",
134      "last_breached_at": "1990-05-29",
135      "domain_registered_at": "1990-05-29",
136      "domain_is_free_provider": "yes",
137      "domain_is_custom": "yes",
138      "domain_is_disposable": "yes",
139      "top_level_domain_is_suspicious": "yes",
140      "linked_services": [
141        "apple"
142      ]
143    },
144    "phone": {
145      "linked_services": [
146        "apple"
147      ]
148    },
149    "devices": [
150      {
151        "ip_proxy_type": "none_detected",
152        "ip_spam_list_count": 1,
153        "ip_timezone_offset": "+06:00:00"
154      }
155    ],
156    "identity_abuse_signals": {
157      "synthetic_identity": {
158        "score": 0
159      },
160      "stolen_identity": {
161        "score": 0
162      }
163    }
164  },
165  "watchlist_screening_id": "scr_52xR9LKo77r1Np",
166  "redacted_at": "2020-07-24T03:26:02Z",
167  "request_id": "saKrIBuEB9qJZng"
168}
Was this helpful?

Webhooks

STATUS_UPDATED

Fired when the status of an identity verification has been updated, which can be triggered via the dashboard or the API.

webhook_type
string
IDENTITY_VERIFICATION
webhook_code
string
STATUS_UPDATED
identity_verification_id
string
The ID of the associated Identity Verification attempt.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "IDENTITY_VERIFICATION",
3  "webhook_code": "STATUS_UPDATED",
4  "identity_verification_id": "idv_52xR9LKo77r1Np",
5  "environment": "production"
6}
Was this helpful?

STEP_UPDATED

Fired when an end user has completed a step of the Identity Verification process.

webhook_type
string
IDENTITY_VERIFICATION
webhook_code
string
STEP_UPDATED
identity_verification_id
string
The ID of the associated Identity Verification attempt.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "IDENTITY_VERIFICATION",
3  "webhook_code": "STEP_UPDATED",
4  "identity_verification_id": "idv_52xR9LKo77r1Np",
5  "environment": "production"
6}
Was this helpful?

RETRIED

Fired when identity verification has been retried, which can be triggered via the dashboard or the API.

webhook_type
string
IDENTITY_VERIFICATION
webhook_code
string
RETRIED
identity_verification_id
string
The ID of the associated Identity Verification attempt.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "IDENTITY_VERIFICATION",
3  "webhook_code": "RETRIED",
4  "identity_verification_id": "idv_52xR9LKo77r1Np",
5  "environment": "production"
6}
Was this helpful?

auth partnerships apex clearing

Add Apex Fintech Solutions to your app

Use Apex Fintech Solutions with Plaid Auth to send and receive payments!

Partnership Apex Fintech Solutions logo

Overview

Plaid and Apex Fintech Solutions have partnered to offer frictionless linking of investors’ bank accounts and their brokerage accounts. With this integration, Apex Fintech Solutions and Plaid clients will not ever need to handle bank account and routing numbers.

With the Plaid + Apex Fintech Solutions integration, investors can onboard with ease by verifying their bank accounts in seconds using Plaid Link, a drop-in front-end module that handles input validation, error handling, and multi-factor authentication. Clients use Plaid Link to instantly authenticate your investor’s account and generate a processor token, so Apex Fintech Solutions can then link the investor’s account to their brokerage account. Investors can then immediately use the link to fund their brokerage account via ACH’s. This process provides a seamless brokerage account funding experience to investors.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Apex Fintech Solutions account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Apex Fintech Solutions processor_token, which allows you to quickly and securely verify a bank funding source via Apex Fintech Solutions's API without having to store any sensitive banking information. Utilizing Plaid + Apex Fintech Solutions enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Apex Fintech Solutions in order to use the Plaid + Apex Fintech Solutions integration. You'll also need to enable your Plaid account for the Apex Fintech Solutions integration.

First, you will need to work with the Apex Fintech Solutions team to sign up for a Apex Fintech Solutions account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Apex Fintech Solutions to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Apex Fintech Solutions processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Apex Fintech Solutions, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Apex Fintech Solutions processor_token. You'll send this token to Apex Fintech Solutions and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Apex Fintech Solutions processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'apex_clearing',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Apex Fintech Solutions Production credentials prior to initiating live payment transactions in the Apex Fintech Solutions API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

auth partnerships highnote

Add Highnote to your app

Use Highnote with Plaid Auth to send and receive payments!

Partnership Highnote logo

Overview

Plaid and Highnote have partnered to offer frictionless money transfers for your card product without the need to ever handle an account or routing number. For card issuance customers, use Plaid Link to instantly authenticate your customer's account and automatically generate a Highnote Processor Token so that your customers can move funds between their card account(s) and external bank account(s).

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Highnote account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Highnote processor_token, which allows you to quickly and securely verify a bank funding source via Highnote's API without having to store any sensitive banking information. Utilizing Plaid + Highnote enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Highnote in order to use the Plaid + Highnote integration. You'll also need to enable your Plaid account for the Highnote integration.

First, you will need to work with the Highnote team to sign up for a Highnote account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Highnote to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Highnote processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Highnote, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Highnote processor_token. You'll send this token to Highnote and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Highnote processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'highnote',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Highnote Production credentials prior to initiating live payment transactions in the Highnote API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

transfer dashboard

Transfer status in Dashboard

Learn how to view Transfer status in Dashboard

Overview

The Plaid Dashboard contains a high-level overview of your transfers activity, including total amount of money transferred and return rate. To view it, Go to Activity->Transfers.

image of Plaid Transfer Dashboard

You can also view transfer activity, including detailed status of each individual transfer. The transfer activity page shows information similar to that returned by the transfer status endpoints such as /transfer/get and /transfer/event/list.

image of Plaid Transfer Dashboard

auth partnerships gusto

Add Gusto to your app

Use Gusto with Plaid Auth to send and receive payments!

Partnership Gusto logo

Overview

Gusto and Plaid have partnered so your customers can quickly and easily configure company bank accounts for seamless, in-app payroll.

You shouldn’t compromise on payroll accuracy and compliance for your customers and their employees. With Gusto Embedded Payroll’s APIs, you can leverage the road-tested payroll engine and expertise of Gusto to build payroll capabilities directly into your platform.

This integration allows your customers to easily connect company bank accounts through Plaid’s Auth flow. A processor_token is a Plaid token used by Gusto to make API calls on your behalf. You will generate a processor_token on behalf of the customer and then pass that token to Gusto. The token allows Gusto to instantly retrieve bank account details, so you don’t need to store and protect sensitive bank information.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Gusto account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Gusto processor_token, which allows you to quickly and securely verify a bank funding source via Gusto's API without having to store any sensitive banking information. Utilizing Plaid + Gusto enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Gusto in order to use the Plaid + Gusto integration. You'll also need to enable your Plaid account for the Gusto integration.

First, you will need to work with the Gusto team to sign up for a Gusto account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Gusto to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Gusto processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Gusto, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Gusto processor_token. You'll send this token to Gusto and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Gusto processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'gusto',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Gusto Production credentials prior to initiating live payment transactions in the Gusto API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

auth coverage

Full Auth coverage

Support Auth for all US financial institutions

Overview

Instant Auth covers approximately 90% of users' eligible bank accounts. For the remaining ~10%, Plaid offers users the ability to connect their accounts through a combination of verifying micro-deposits and account credentials.

Our video tutorial also provides a comprehensive guide to adding Auth using all four flows

To support Auth for all of your users, this guide will show you how to build the following Auth flows:

  • Instant Auth: User enters their credentials and is authenticated immediately. This is the default flow. No extra steps are necessary to enable Instant Auth if you have already integrated Auth into your app.
  • Instant Match (US only): User enters their credentials, account number, and routing number. Plaid matches user input and authenticates immediately. No extra steps are necessary to enable Instant Match if you have already integrated Auth into your app; it will appear automatically as long as country_codes is set to ['US'].
  • Automated Micro-deposits (US only): User enters their credentials, account number, and routing number. Plaid makes a micro-deposit and automatically verifies the deposit in as little as one to two business days.
  • Same Day Micro-deposits (US only): User enters account and routing numbers. Plaid makes a Same Day ACH micro-deposit and the user manually verifies the code in as little as one business day.
Auth Overview Diagram

Plaid will attempt to use the flows in the order of preference listed above. For example, the Automated Micro-deposits flow will only be used if both Instant Match and Instant Auth are unavailable for a given institution.

For each of these flows, Plaid will automatically prompt the user for the appropriate information. If a user cannot find their financial institution when searching, Plaid Link will prompt them to link with account numbers, where they can enter the Same Day Micro-deposits flow.

To see which Auth flows a given institution supports, you can call /institutions/get with options.include_auth_metadata set to true. The results will be returned in the auth_metadata.supported_methods object in the response. Alternatively, you can see this information on the Institution Status page in the Plaid Dashboard.

Each section in this guide is broken down into steps and supporting code samples.

Next steps

payment initiation

Introduction to Payment Initiation

Initiate payments within your app using the Payment Initiation (Europe) product.

Explore

Overview

Plaid's Payment Initiation product enables your users to make real-time payments without manually entering their account number and sort code, or leaving your app. For example, your app might allow users to pay you. You can also provide transfers to a third party, such as in a marketplace application. You can create both one-time payments (also known as Single Immediate Payments) as well as standing orders that make recurring payments on a regular schedule. By combining Payment Initiation with the optional Virtual Accounts product, you can enable even more functionality, like sending refunds to users, allowing your users to cash out a credit balance to a bank account, or gaining granular visibility into the settlement status of a payment.

There are two ways to integrate with Plaid for Payment Initiation:

  1. Using Classic Link, which is optimized for conversion and allows customers to use existing Plaid Link front-end components to get up and running quickly. You can choose to create your own custom loading states to completely own the UI/UX or use Plaid loading states to save developer time.
  2. Using the white-label Modular Link experience, which allows customers to own the end-to-end experience.

See the Add Payment Initiation to your App guide to learn more about the product and how to implement it.

Payment Initiation is UK and Europe-only. Looking for similar capabilities in the US? Check out the Transfer docs.

Supported countries

For a full, up-to-date list of supported countries for Payment Initiation, see Plaid Global Coverage.

Recurring Payments

Enable your users to make Variable Recurring Payments and set up Standing Orders. With Variable Recurring Payments (VRP), your users can set up repeat payments for different amounts and intervals. With Standing Orders, your users can set up repeat payments for a fixed amount.

Variable Recurring Payments (beta) (UK)

A Variable Recurring Payment (VRP) allows for setup of a recurring payment consent, which can then be used for a series of ongoing payments. This consent can be created with the Payment Initiation product. For a VRP, the source and the recipient must be in the UK. The payment consent must be created using the /payment_initiation/consent/create endpoint with parameters authorised by the user before payments are initiated. To join the VRP beta, please contact your Plaid Account Manager.

Standing Orders (UK)

A standing order is a recurring payment, which can be created with the Payment Initiation product. For a standing order payment, the recipient must be in the UK. The standing order creation flow is the same as the Payment Initiation flow described above. When creating a standing order, the frequency of the payment must be provided to /payment_initiation/payment/create. Note that standing orders are billed at a different rate than other calls to /payment_initiation/payment/create; for details, contact your Plaid Account Manager.

Testing Payment Initiation

Payment Initiation can immediately be tried out in the Sandbox environment. It uses test data and does not interact with financial institutions. In order to test Payment Initiation against live Items in either Development or Production, you will need to first request access by submitting a product access request Support ticket explaining your use case.

Payment Initiation can be tested with real money using the Development environment. However in the Development environment, payments must be below 5 GBP or other chosen currency; otherwise they will be blocked.

QR code authentication

For some institutions, Plaid supports the use of QR codes to streamline the OAuth authentication process that may be required during the Payment Initiation flow. For more information, see the OAuth guide.

Payment Monitoring

Plaid monitors all recipient and payment creation attempts to review and block suspicious activity. If your payment is blocked, /payment_initiation/payment/create will return a PAYMENT_BLOCKED error code. In the Development environment, payments must be below 5 GBP or other chosen currency. For details on any payment limits in Production, contact your Plaid Account Manager.

Sample app

For a simple real-world implementation of Payment Initiation, see the Payment Initiation Pattern App on GitHub, which uses Payment Initiation in an account funding use case.

Next steps

To get started building with Payment Initiation, see Add Payment Initiation to your App.

If you're ready to launch to Production, see the Launch checklist.

api items

Item endpoints

API reference for retrieving and deleting Items

Endpoints
/item/getRetrieve an Item
/item/removeRemove an Item
/item/webhook/updateUpdate a webhook URL
See also
/sandbox/public_token/createCreate a test Item (Sandbox only)
/sandbox/item/reset_loginForce an Item into an error state (Sandbox only)
/sandbox/item/set_verification_statusSet verification status (Sandbox only)
/sandbox/item/fire_webhookFire a test webhook (Sandbox only)
/item/access_token/invalidateRotate an access token without deleting the Item
Webhooks
ERRORItem has entered an error state
NEW_ACCOUNTS_AVAILABLENew account detected for an Item
PENDING_EXPIRATIONItem access is about to expire
USER_PERMISSION_REVOKEDThe user has revoked access to an Item
WEBHOOK_UPDATE_ACKNOWLEDGEDItem webhook URL updated

Endpoints

For Item endpoints related to Item tokens, see Token endpoints.

/item/get

Retrieve an Item

Returns information about the status of an Item.

item/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
Select group for content switcher
Select Language
1const request: ItemGetRequest = {
2  access_token: accessToken,
3};
4try {
5  const response = await plaidClient.itemGet(request);
6  const item = response.data.item;
7  const status = response.data.status;
8} catch (error) {
9  // handle error
10}
item/get

Response fields and example

item
object
Metadata about the Item.
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
nullablestring
The Plaid Institution ID associated with the Item. Field is null for Items created via Same Day Micro-deposits.
webhook
nullablestring
The URL registered to receive webhooks for the Item.
error
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
available_products
[string]
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
billed_products
[string]
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available_products. Note - billed_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
products
[string]
A list of initialized products for the Item. In almost all cases, this will be the same as the billed_products field. For some products, it is possible for the product to be initialized on an Item but not yet billed (e.g. Assets, before /asset_report/create has been called), in which case the product may appear in products but not in billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consented_products
[string]
A list of products that have gone through consent collection for the Item. Only present for those enabled in the Data Transparency beta. If you are not enrolled in Data Transparency, this field is not used.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consent_expiration_time
nullablestring
The RFC 3339 timestamp after which the consent provided by the end user will expire. Upon consent expiration, the item will enter the ITEM_LOGIN_REQUIRED error state. To circumvent the ITEM_LOGIN_REQUIRED error and maintain continuous consent, the end user can reauthenticate via Link’s update mode in advance of the consent expiration time.
Note - This is only relevant for certain OAuth-based institutions. For all other institutions, this field will be null.

Format: date-time
update_type
string
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication.
background - Item can be updated in the background
user_present_required - Item requires user interaction to be updated

Possible values: background, user_present_required
status
nullableobject
An object with information about the status of the Item.
investments
nullableobject
Information about the last successful and failed investments update for the Item.
last_successful_update
nullablestring
ISO 8601 timestamp of the last successful investments update for the Item. The status will update each time Plaid successfully connects with the institution, regardless of whether any new data is available in the update.

Format: date-time
last_failed_update
nullablestring
ISO 8601 timestamp of the last failed investments update for the Item. The status will update each time Plaid fails an attempt to connect with the institution, regardless of whether any new data is available in the update.

Format: date-time
transactions
nullableobject
Information about the last successful and failed transactions update for the Item.
last_successful_update
nullablestring
ISO 8601 timestamp of the last successful transactions update for the Item. The status will update each time Plaid successfully connects with the institution, regardless of whether any new data is available in the update.

Format: date-time
last_failed_update
nullablestring
ISO 8601 timestamp of the last failed transactions update for the Item. The status will update each time Plaid fails an attempt to connect with the institution, regardless of whether any new data is available in the update.

Format: date-time
last_webhook
nullableobject
Information about the last webhook fired for the Item.
sent_at
nullablestring
ISO 8601 timestamp of when the webhook was fired.

Format: date-time
code_sent
nullablestring
The last webhook code sent.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "item": {
3    "available_products": [
4      "balance",
5      "auth"
6    ],
7    "billed_products": [
8      "identity",
9      "transactions"
10    ],
11    "error": null,
12    "institution_id": "ins_109508",
13    "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
14    "update_type": "background",
15    "webhook": "https://plaid.com/example/hook",
16    "consent_expiration_time": null
17  },
18  "status": {
19    "transactions": {
20      "last_successful_update": "2019-02-15T15:52:39Z",
21      "last_failed_update": "2019-01-22T04:32:00Z"
22    },
23    "last_webhook": {
24      "sent_at": "2019-02-15T15:53:00Z",
25      "code_sent": "DEFAULT_UPDATE"
26    }
27  },
28  "request_id": "m8MDnv9okwxFNBV"
29}
Was this helpful?

/item/remove

Remove an Item

The /item/remove endpoint allows you to remove an Item. Once removed, the access_token, as well as any processor tokens or bank account tokens associated with the Item, is no longer valid and cannot be used to access any data that was associated with the Item.
Note that in the Development environment, issuing an /item/remove request will not decrement your live credential count. To increase your credential account in Development, contact Support.
Also note that for certain OAuth-based institutions, an Item removed via /item/remove may still show as an active connection in the institution's OAuth permission manager.
API versions 2019-05-29 and earlier return a removed boolean as part of the response.

item/remove

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
Select group for content switcher
Select Language
1const request: ItemRemoveRequest = {
2  access_token: accessToken,
3};
4try {
5  const response = await plaidClient.itemRemove(request);
6  // The Item was removed, access_token is now invalid
7} catch (error) {
8  // handle error
9}
10
11// The Item was removed, access_token is now invalid
item/remove

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "m8MDnv9okwxFNBV"
3}
Was this helpful?

/item/webhook/update

Update Webhook URL

The POST /item/webhook/update allows you to update the webhook URL associated with an Item. This request triggers a WEBHOOK_UPDATE_ACKNOWLEDGED webhook to the newly specified webhook URL.

item/webhook/update

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
webhook
string
The new webhook URL to associate with the Item. To remove a webhook from an Item, set to null.
Select group for content switcher
Select Language
1// Update the webhook associated with an Item
2const request: ItemWebhookUpdateRequest = {
3  access_token: accessToken,
4  webhook: 'https://example.com/updated/webhook',
5};
6try {
7  const response = await plaidClient.itemWebhookUpdate(request);
8  // A successful response indicates that the webhook has been
9  // updated. An acknowledgement webhook will also be fired.
10  const item = response.data.item;
11} catch (error) {
12  // handle error
13}
item/webhook/update

Response fields and example

item
object
Metadata about the Item.
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
nullablestring
The Plaid Institution ID associated with the Item. Field is null for Items created via Same Day Micro-deposits.
webhook
nullablestring
The URL registered to receive webhooks for the Item.
error
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
available_products
[string]
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
billed_products
[string]
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available_products. Note - billed_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
products
[string]
A list of initialized products for the Item. In almost all cases, this will be the same as the billed_products field. For some products, it is possible for the product to be initialized on an Item but not yet billed (e.g. Assets, before /asset_report/create has been called), in which case the product may appear in products but not in billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consented_products
[string]
A list of products that have gone through consent collection for the Item. Only present for those enabled in the Data Transparency beta. If you are not enrolled in Data Transparency, this field is not used.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consent_expiration_time
nullablestring
The RFC 3339 timestamp after which the consent provided by the end user will expire. Upon consent expiration, the item will enter the ITEM_LOGIN_REQUIRED error state. To circumvent the ITEM_LOGIN_REQUIRED error and maintain continuous consent, the end user can reauthenticate via Link’s update mode in advance of the consent expiration time.
Note - This is only relevant for certain OAuth-based institutions. For all other institutions, this field will be null.

Format: date-time
update_type
string
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication.
background - Item can be updated in the background
user_present_required - Item requires user interaction to be updated

Possible values: background, user_present_required
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "item": {
3    "available_products": [
4      "balance",
5      "identity",
6      "payment_initiation",
7      "transactions"
8    ],
9    "billed_products": [
10      "assets",
11      "auth"
12    ],
13    "consent_expiration_time": null,
14    "error": null,
15    "institution_id": "ins_117650",
16    "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
17    "update_type": "background",
18    "webhook": "https://www.genericwebhookurl.com/webhook"
19  },
20  "request_id": "vYK11LNTfRoAMbj"
21}
Was this helpful?

Webhooks

Webhooks are used to communicate changes to an Item, such as an updated webhook, or errors encountered with an Item. The error typically requires user action to resolve, such as when a user changes their password. All Item webhooks have a webhook_type of ITEM.

ERROR

Fired when an error is encountered with an Item. The error can be resolved by having the user go through Link’s update mode.

webhook_type
string
ITEM
webhook_code
string
ERROR
item_id
string
The item_id of the Item associated with this webhook, warning, or error
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "ITEM",
3  "webhook_code": "ERROR",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "error": {
6    "display_message": null,
7    "error_code": "ITEM_LOGIN_REQUIRED",
8    "error_message": "the login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state",
9    "error_type": "ITEM_ERROR",
10    "status": 400
11  },
12  "environment": "production"
13}
Was this helpful?

NEW_ACCOUNTS_AVAILABLE

Fired when Plaid detects a new account for Items created or updated with Account Select v2. Upon receiving this webhook, you can prompt your users to share new accounts with you through Account Select v2 update mode.

webhook_type
string
ITEM
webhook_code
string
NEW_ACCOUNTS_AVAILABLE
item_id
string
The item_id of the Item associated with this webhook, warning, or error
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "ITEM",
3  "webhook_code": "NEW_ACCOUNTS_AVAILABLE",
4  "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ",
5  "error": null,
6  "environment": "production"
7}
Was this helpful?

PENDING_EXPIRATION

Fired when an Item’s access consent is expiring in 7 days. Some Items have explicit expiration times and we try to relay this when possible to reduce service disruption. This can be resolved by having the user go through Link’s update mode.

webhook_type
string
ITEM
webhook_code
string
PENDING_EXPIRATION
item_id
string
The item_id of the Item associated with this webhook, warning, or error
consent_expiration_time
string
The date and time at which the Item's access consent will expire, in ISO 8601 format

Format: date-time
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "ITEM",
3  "webhook_code": "PENDING_EXPIRATION",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "consent_expiration_time": "2020-01-15T13:25:17.766Z",
6  "environment": "production"
7}
Was this helpful?

USER_PERMISSION_REVOKED

The USER_PERMISSION_REVOKED webhook may be fired when an end user has used either the my.plaid.com portal or the financial institution’s OAuth consent portal to revoke the permission that they previously granted to access an Item. This webhook is not guaranteed to always be fired upon consent revocation, since some institutions’ consent portals do not trigger this webhook. Once access to an Item has been revoked, it cannot be restored. If the user subsequently returns to your application, a new Item must be created for the user.

webhook_type
string
ITEM
webhook_code
string
USER_PERMISSION_REVOKED
item_id
string
The item_id of the Item associated with this webhook, warning, or error
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "ITEM",
3  "webhook_code": "USER_PERMISSION_REVOKED",
4  "error": {
5    "error_code": "USER_PERMISSION_REVOKED",
6    "error_message": "the holder of this account has revoked their permission for your application to access it",
7    "error_type": "ITEM_ERROR",
8    "status": 400
9  },
10  "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ",
11  "environment": "production"
12}
Was this helpful?

WEBHOOK_UPDATE_ACKNOWLEDGED

Fired when an Item's webhook is updated. This will be sent to the newly specified webhook.

webhook_type
string
ITEM
webhook_code
string
WEBHOOK_UPDATE_ACKNOWLEDGED
item_id
string
The item_id of the Item associated with this webhook, warning, or error
new_webhook_url
string
The new webhook URL
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "ITEM",
3  "webhook_code": "WEBHOOK_UPDATE_ACKNOWLEDGED",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "error": null,
6  "new_webhook_url": "https://plaid.com/example/webhook",
7  "environment": "production"
8}
Was this helpful?

assets waitlist

Product waitlist

Features that are under development

Overview

Bank Statements allows you to retrieve a PDF copy of an end user's statement. The Bank Statements product simplifies the process of collecting documents for loan verification purposes or rental application review purposes, among others.

Hosted Link is an easier and faster way to integrate with Plaid. With Hosted Link, Plaid will host the Link experience and can even deliver the URL to the Link session to your customers via text or email, eliminating the need for any front-end implementation work.

api products beacon

Beacon

API reference for Beacon endpoints

Add and report users on the Plaid Beacon network.

Endpoints
/beacon/user/createCreate and scan a Beacon User against a Beacon Program
/beacon/user/getFetch a beacon user
/beacon/report/createCreate a fraud report for a given Beacon User

/beacon/user/create

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or submit a product access Support ticket.

Create a Beacon User

Create and scan a Beacon User against your Beacon Program, according to your program's settings.
When you submit a new user to /beacon/user/create, several checks are performed immediately:
- The user's PII (provided within the user object) is searched against all other users within the Beacon Program you specified. If a match is found that violates your program's "Duplicate Information Filtering" settings, the user will be returned with a status of pending_review.
- The user's PII is also searched against all fraud reports created by your organization across all of your Beacon Programs. If the user's data matches a fraud report that your team created, the user will be returned with a status of rejected.
- Finally, the user's PII is searched against all fraud report shared with the Beacon Network by other companies. If a matching fraud report is found, the user will be returned with a pending_review status if your program has enabled automatic flagging based on network fraud.

beacon/user/create

Request fields and example

program_id
requiredstring
ID of the associated Beacon Program.
client_user_id
requiredstring
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
user
requiredobject
A Beacon User's data which is used to check against duplicate records and the Beacon Fraud Network.
date_of_birth
requiredstring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
name
requiredobject
The full name for a given Beacon User.
given_name
requiredstring
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
requiredstring
A string with at least one non-whitespace character, with a max length of 100 characters.
address
requiredobject
Home address for the associated user. For more context on this field, see Input Validation by Country.
street
requiredstring
The primary street portion of an address. If the user has submitted their address, this field will always be filled.
street2
string
Extra street information, like an apartment or suite number.
city
requiredstring
City from the end user's address
region
string
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
string
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
requiredstring
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
email_address
string
A valid email address.

Format: email
phone_number
string
A phone number in E.164 format.
id_number
object
The ID number associated with a Beacon User.
value
requiredstring
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
requiredstring
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
ip_address
string
An IPv4 or IPV6 address.
report
object
Data for creating a Beacon Report as part of an initial Beacon User creation. Providing a fraud report as part of an initial Beacon User creation will omit the Beacon User from any billing charges.
type
requiredstring
The type of Beacon Report.
first_party: If this is the same individual as the one who submitted the KYC.
third_party: If this is a different individual from the one who submitted the KYC.
synthetic: If this is an individual using fabricated information.
account_takeover: If this individual's account was compromised.
unknown: If you aren't sure who committed the fraud.

Possible values: first_party, third_party, synthetic, account_takeover, unknown
fraud_date
requiredstring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
fraud_amount
object
The amount and currency of the fraud or attempted fraud. fraud_amount should be omitted to indicate an unknown fraud amount.
iso_currency_code
requiredstring
An ISO-4217 currency code.

Possible values: USD
Min length: 3
value
requirednumber
The amount value. This value can be 0 to indicate no money was lost. Must not contain more than two digits of precision (e.g., 1.23).

Format: double
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
Select Language
1const request: BeaconUserCreateRequest = {
2  program_id: 'becprg_11111111111111',
3  client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
4  user: {
5    email_address: 'user@example.com',
6    date_of_birth: '1975-01-18',
7    name: {
8      given_name: 'Leslie',
9      family_name: 'Knope',
10    },
11    address: {
12      street: '123 Main St.',
13      street2: 'Unit 42',
14      city: 'Pawnee',
15      region: 'IN',
16      postal_code: '46001',
17      country: 'US',
18    },
19  },
20  report: {
21    type: 'first_party',
22    fraud_date: '1990-05-29',
23  },
24};
25
26try {
27  const response = await plaidClient.beaconUserCreate(request);
28  console.log(response.status.value);
29} catch (error) {
30  // handle error
31}
beacon/user/create

Response fields and example

id
string
ID of the associated Beacon User.
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
updated_at
string
An ISO8601 formatted timestamp. This field indicates the last time the resource was modified.

Format: date-time
status
string
A status of a Beacon User.
rejected: The Beacon User has been rejected for fraud. Users can be automatically or manually rejected.
pending_review: The Beacon User has been marked for review.
cleared: The Beacon User has been cleared of fraud.

Possible values: rejected, pending_review, cleared
program_id
string
ID of the associated Beacon Program.
client_user_id
string
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
user
object
A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.
date_of_birth
string
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
name
object
The full name for a given Beacon User.
given_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
address
object
Even if an address has been collected, some fields may be null depending on the region's addressing system. For example:
Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include a postal code
street
string
The primary street portion of an address. If the user has submitted their address, this field will always be filled.
street2
nullablestring
Extra street information, like an apartment or suite number.
city
string
City from the end user's address
region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
nullablestring
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
email_address
nullablestring
A valid email address.

Format: email
phone_number
nullablestring
A phone number in E.164 format.
id_number
object
The ID number associated with a Beacon User.
value
string
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
string
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
ip_address
nullablestring
An IPv4 or IPV6 address.
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating what caused a resource to be changed or updated.
dashboard - The resource was created or updated by a member of your team via the Plaid dashboard.
api - The resource was created or updated via the Plaid API.
system - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be system.
bulk_import - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be bulk_import.

Possible values: dashboard, api, system, bulk_import
dashboard_user_id
nullablestring
ID of the associated user.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "becusr_11111111111111",
3  "created_at": "2020-07-24T03:26:02Z",
4  "updated_at": "2020-07-24T03:26:02Z",
5  "status": "cleared",
6  "program_id": "becprg_11111111111111",
7  "client_user_id": "your-db-id-3b24110",
8  "user": {
9    "date_of_birth": "1990-05-29",
10    "name": {
11      "given_name": "Leslie",
12      "family_name": "Knope"
13    },
14    "address": {
15      "street": "123 Main St.",
16      "street2": "Unit 42",
17      "city": "Pawnee",
18      "region": "IN",
19      "postal_code": "46001",
20      "country": "US"
21    },
22    "email_address": "user@example.com",
23    "phone_number": "+19876543212",
24    "id_number": {
25      "value": "123456789",
26      "type": "us_ssn"
27    },
28    "ip_address": "192.0.2.42"
29  },
30  "audit_trail": {
31    "source": "dashboard",
32    "dashboard_user_id": "54350110fedcbaf01234ffee"
33  },
34  "request_id": "saKrIBuEB9qJZng"
35}
Was this helpful?

/beacon/user/get

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or submit a product access Support ticket.

Get a Beacon User

Fetch a Beacon User.
The Beacon User is returned with all of their associated information and a status based on the Beacon Network duplicate record and fraud checks.

beacon/user/get

Request fields and example

beacon_user_id
requiredstring
ID of the associated Beacon User.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
Select Language
1const request: BeaconUserGetRequest = {
2  beacon_user_id: 'becusr_11111111111111',
3};
4
5try {
6  const response = await plaidClient.beaconUserGet(request);
7} catch (error) {
8  // handle error
9}
beacon/user/get

Response fields and example

id
string
ID of the associated Beacon User.
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
updated_at
string
An ISO8601 formatted timestamp. This field indicates the last time the resource was modified.

Format: date-time
status
string
A status of a Beacon User.
rejected: The Beacon User has been rejected for fraud. Users can be automatically or manually rejected.
pending_review: The Beacon User has been marked for review.
cleared: The Beacon User has been cleared of fraud.

Possible values: rejected, pending_review, cleared
program_id
string
ID of the associated Beacon Program.
client_user_id
string
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
user
object
A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.
date_of_birth
string
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
name
object
The full name for a given Beacon User.
given_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
address
object
Even if an address has been collected, some fields may be null depending on the region's addressing system. For example:
Addresses from the United Kingdom will not include a region
Addresses from Hong Kong will not include a postal code
street
string
The primary street portion of an address. If the user has submitted their address, this field will always be filled.
street2
nullablestring
Extra street information, like an apartment or suite number.
city
string
City from the end user's address
region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
nullablestring
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
email_address
nullablestring
A valid email address.

Format: email
phone_number
nullablestring
A phone number in E.164 format.
id_number
object
The ID number associated with a Beacon User.
value
string
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
string
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
ip_address
nullablestring
An IPv4 or IPV6 address.
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating what caused a resource to be changed or updated.
dashboard - The resource was created or updated by a member of your team via the Plaid dashboard.
api - The resource was created or updated via the Plaid API.
system - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be system.
bulk_import - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be bulk_import.

Possible values: dashboard, api, system, bulk_import
dashboard_user_id
nullablestring
ID of the associated user.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "becusr_11111111111111",
3  "created_at": "2020-07-24T03:26:02Z",
4  "updated_at": "2020-07-24T03:26:02Z",
5  "status": "cleared",
6  "program_id": "becprg_11111111111111",
7  "client_user_id": "your-db-id-3b24110",
8  "user": {
9    "date_of_birth": "1990-05-29",
10    "name": {
11      "given_name": "Leslie",
12      "family_name": "Knope"
13    },
14    "address": {
15      "street": "123 Main St.",
16      "street2": "Unit 42",
17      "city": "Pawnee",
18      "region": "IN",
19      "postal_code": "46001",
20      "country": "US"
21    },
22    "email_address": "user@example.com",
23    "phone_number": "+19876543212",
24    "id_number": {
25      "value": "123456789",
26      "type": "us_ssn"
27    },
28    "ip_address": "192.0.2.42"
29  },
30  "audit_trail": {
31    "source": "dashboard",
32    "dashboard_user_id": "54350110fedcbaf01234ffee"
33  },
34  "request_id": "saKrIBuEB9qJZng"
35}
Was this helpful?

/beacon/report/create

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or submit a product access Support ticket.

Create a Beacon Report

Create a fraud report for a given Beacon User.
Note: If you are creating users with the express purpose of providing historical fraud data, you should use the /beacon/user/create endpoint instead and embed the fraud report in the request. This will ensure that the Beacon User you create will not be subject to any billing costs.

beacon/report/create

Request fields and example

beacon_user_id
requiredstring
ID of the associated Beacon User.
type
requiredstring
The type of Beacon Report.
first_party: If this is the same individual as the one who submitted the KYC.
third_party: If this is a different individual from the one who submitted the KYC.
synthetic: If this is an individual using fabricated information.
account_takeover: If this individual's account was compromised.
unknown: If you aren't sure who committed the fraud.

Possible values: first_party, third_party, synthetic, account_takeover, unknown
fraud_date
requiredstring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
fraud_amount
object
The amount and currency of the fraud or attempted fraud. fraud_amount should be omitted to indicate an unknown fraud amount.
iso_currency_code
requiredstring
An ISO-4217 currency code.

Possible values: USD
Min length: 3
value
requirednumber
The amount value. This value can be 0 to indicate no money was lost. Must not contain more than two digits of precision (e.g., 1.23).

Format: double
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
Select Language
1const request: BeaconReportCreateRequest = {
2  beacon_user_id: 'becusr_11111111111111',
3  type: 'first_party',
4  fraud_date: '1975-01-18',
5};
6
7try {
8  const response = await plaidClient.beaconReportCreate(request);
9} catch (error) {
10  // handle error
11}
beacon/report/create

Response fields and example

id
string
ID of the associated Beacon Report.
beacon_user_id
string
ID of the associated Beacon User.
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
type
string
The type of Beacon Report.
first_party: If this is the same individual as the one who submitted the KYC.
third_party: If this is a different individual from the one who submitted the KYC.
synthetic: If this is an individual using fabricated information.
account_takeover: If this individual's account was compromised.
unknown: If you aren't sure who committed the fraud.

Possible values: first_party, third_party, synthetic, account_takeover, unknown
fraud_date
string
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
fraud_amount
object
The amount and currency of the fraud or attempted fraud. fraud_amount should be omitted to indicate an unknown fraud amount.
iso_currency_code
string
An ISO-4217 currency code.

Possible values: USD
Min length: 3
value
number
The amount value. This value can be 0 to indicate no money was lost. Must not contain more than two digits of precision (e.g., 1.23).

Format: double
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating what caused a resource to be changed or updated.
dashboard - The resource was created or updated by a member of your team via the Plaid dashboard.
api - The resource was created or updated via the Plaid API.
system - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be system.
bulk_import - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be bulk_import.

Possible values: dashboard, api, system, bulk_import
dashboard_user_id
nullablestring
ID of the associated user.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "becrpt_11111111111111",
3  "beacon_user_id": "becusr_11111111111111",
4  "created_at": "2020-07-24T03:26:02Z",
5  "type": "first_party",
6  "fraud_date": "1990-05-29",
7  "fraud_amount": {
8    "iso_currency_code": "USD",
9    "value": 100
10  },
11  "audit_trail": {
12    "source": "dashboard",
13    "dashboard_user_id": "54350110fedcbaf01234ffee"
14  },
15  "request_id": "saKrIBuEB9qJZng"
16}
Was this helpful?

monitor

Introduction to Monitor

Sanction, PEP, and watchlist screening for anti-money laundering compliance

Explore API

Overview

Monitor detects if your customers are on government watchlists, using modern APIs that reduce false positives and increase efficiency. Monitor screens users against a number of sanction and PEP lists. Sanction lists are updated daily and can be used for daily automated re-scans. Any hits will be exposed via both a user-friendly dashboard UI and via API, for use with either manual or automated review workflows. Monitor also integrates directly with Identity Verification for an end-to-end verification and KYC solution.

Monitor can be used to screen end users in any country. To integrate with Monitor, your company must be based in the US or Canada (support for additional countries coming soon).

Creating a program

Access to Monitor in the Sandbox test environment is not provided by default. To obtain Sandbox access, request product access from the Dashboard.

The first step to integrating is logging into the dashboard and accessing the New Program page. Programs help you to define the settings and workflows for conducting watchlist screenings in your organization. For example, you can define match sensitivities, which lists are being screened, and the behavior of ongoing screening. For more details on the configuration of screenings and how matches are determined, see Algorithms and Lists.

Monitor allows you to start a customer in one program and then move them to a different one. To move users between programs, call /watchlist_screening/individual/update or /watchlist_screening/entity/update with the watchlist_screening_id you want to move and the ID of the program you want to move it to in the watchlist_program_id field. Customers cannot be in multiple programs at once.

The number of programs you wish to maintain will vary based on the complexity of your organization. Many companies choose to split up programs such that each program aligns to the compliance ownership within their organization and each reviewer will only see programs they are responsible for. Some common ways of splitting up programs are by product vertical ("Cardholders", "Personal Loans", "FDIC Accounts", etc.), geography ("US Cardholders", "European Cardholders", etc.), risk level ("High Risk Individuals", "Medium Risk Individuals"), or a combination of the above. For ideas about how to split customers up by risk, OFAC has prepared a helpful risk matrix that can provide a baseline for setting initial risk level and then modifying the risk level based on ongoing user behavior. You are allowed to change a program after it has been created, although note that increasing the sensitivity of a program after creation may result in a large influx of new hits.

If your use case involves an ongoing relationship with your customers, Plaid recommends creating at least two programs -- one with rescan enabled for active customers, and one with rescan disabled, for customers who have not yet established an ongoing relationship (for example, customers who have not completed the onboarding experience) or who have closed their accounts. For more details, see Monitor fee model.

Once your first program is created, you can start your integration.

Basic integration overview

This integration overview describes the process for using a Dashboard-based review workflow, which is the most common way to use Monitor. The review process can also be performed using the API; see the API reference for details.

If you are already using Plaid's Identity Verification product:

  1. Use the Enable screening setting in the Identity Verification setup flow to automatically assign users to a Monitor program after they have completed verification.
  2. When your user has successfully completed the Identity Verification process, the response you receive from calling /identity_verification/get will include a watchlist_screening_id value.
  3. Call /watchlist_screening/entity/get or /watchlist_screening/individual/get with this value, and check the status flag on the response.
    • If it is cleared, your customer did not appear on any of your target screening lists.
    • If it is pending_review, your customer received one or more hits and is pending review.
  4. For customers who are pending review, a member of your team will need to review and update the user's status in the Dashboard. When they do (and you have configured your webhooks as described below) you will receive a webhook, SCREENING: STATUS_UPDATED (or ENTITY_SCREENING: STATUS_UPDATED for entities). This webhook will include the watchlist screening id of the individual.
  5. You can then make an additional call to /watchlist_screening/entity/get or /watchlist_screening/individual/get and check the status flag on the response.
    • If it is cleared, the screening hit has been dismissed by a reviewer as invalid.
    • If it is pending_review, a customer that was previously marked as cleared or rejected was marked for review.
    • If it is rejected, your customer received a hit that has been confirmed by a reviewer as a valid match.

If you are not using Identity Verification, the process is slightly different:

  1. Create a customer object using /watchlist_screening/individual/create or /watchlist_screening/entity/create, passing along any verified information you have about your user. While not required, it is recommended to specify a client_user_id, which should refer to an internal ID in your database, to help associate this screening with your customer in the future.
  2. The results of this create call will include a status flag -- either cleared, or pending_review as specified above.
  3. At this point, you can proceed from step 4 in the above workflow.

Configuring webhooks

To complete your integration, you should add a webhook receiver endpoint to your application.

Like Identity Verification, you can configure the webhooks sent by Monitor by visiting the dashboard webhook configuration page. Click New webhook, and then select which events you want to subscribe to. For Monitor, there are two:

Enter the URL of your webhook receiver for the webhook you wish to subscribe to and click Save. Plaid will now send an HTTP POST request to the webhook receiver endpoint every time the event occurs.

For more information on webhooks, see the webhook documentation.

Building a reviewer workflow

This guide assumes that you will be using the dashboard for reviewing hits, but you can also re-create any aspect of the dashboard in your internal applications via the API.

image of Plaid Monitor Dashboard
Assigning hits to reviewers

Once your basic integration is complete, any customers who have potential hits will start showing up on your dashboard. You can assign any screenings that are pending review to different reviewers in your organization. If using an API-based review workflow, you can get a full list of users and their associated user IDs by calling /dashboard_user/list and setting your screening assignee to the desired reviewer.

Preparing for ongoing screening

Monitor updates screening lists daily and supports ongoing daily rescans of your entire customer base to alert you when new hits are discovered. This system is designed around the concept of a living pending_review queue that is updated whenever new hits are found. We recommend that a reviewer log in daily to check the review status on the dashboard. If you prefer to be alerted when a hit is found or to handle hits via automation, you can set up a daily automated job to check /watchlist_screening/individual/hit/list or /watchlist_screening/entity/hit/list once a day to poll any of the screenings that end up in this queue. Then use the associated client_user_id or id to tie the hit back to your internal database and determine if action is required.

Plaid will also fire webhooks to alert you when any new hits are found. Webhooks will contain the watchlist screening id, which you can use to go retrieve any watchlist screening hits that are pending review.

Additional considerations

  • Adding Monitor is not the only part of a successful Anti-Money Laundering program. We highly recommend that you consult with an AML professional to help you build all of the policies and procedures required. AML regulations vary widely for different jurisdictions and industries.
  • Monitor does not blanket ban any countries on your behalf. Some sanction programs effectively prohibit working with certain jurisdictions and it is up to you to ensure that you are only working with individuals from countries that are appropriate for your desired risk levels. For instance, here is an article from OFAC about a "Country List"
  • Monitor is built to make it difficult to overconstrain a search and therefore have false negatives. That being said, if your data inputs are not quality controlled to at least a basic extent, this can result in false negatives or false positives (for example, broad searches based on incomplete names).

Testing Monitor

Monitor is not supported in Plaid's Development environment. Only Production and Sandbox are supported environments. To obtain Sandbox access, file a Product access request.

Sandbox supports a real-world dataset, meaning that sanctioned individuals should show up just as they would in Production. Some example sanctioned individuals and entities you can use for testing purposes include:

Individual NameDate of BirthLocationDocument
Joseph Kony1964-09-18CF
Jianshu Zhou1971-07-15CNE09598913
Ermias GhermayAny day in 1980LY
Entity NameLocationDocument
Iran Mobin Electronic Development CompanyIR10103492170
МИНСКИЙ ОТРЯД МИЛИЦИИ ОСОБОГО НАЗНАЧЕНИЯBY
Islamic Radio And Television UnionAF

Testing Monitor alongside Identity Verification can be a little tricky, as Monitor screens against a real-world dataset, while Identity Verification only supports one single test identity, Leslie Knope. If you wish to test the case of Identity Verification succeeding, but a Monitor screening encountering a hit, you can try one of these options:

  • From the Monitor section of the Dashboard, select the user from the Cleared tab and change their status from "Cleared" to "Pending Review" or "Rejected". This will fire a STATUS_UPDATED webhook, and the user's new screening status will be reflected in the response the next time you call /watchlist_screening/individual/get.
  • You can also create additional watchlist screenings against the same client user ID by calling /watchlist_screening/individual/create with the name and birthday of a real sanctioned individual. This screening will appear in the Monitor dashboard in the "Pending review" section and will be included in the array of screening results that get returned if you call /watchlist_screening/individual/list with this client user ID.

Note that the Sandbox environment sanction and watchlist dataset may be out of date. Make sure all real checks are carried out on the live Production environment.

Additional resources

For a step-by-step walkthrough of implementing Monitor, see the Identity Verification and Monitor solution guide

Next steps

To learn more about building with Monitor, see the Monitor API Reference.

If you're ready to launch to Production, see the Launch checklist.

identity verification

Introduction to Identity Verification

Verify the identity of your users for global KYC and anti-fraud.

Explore API

Overview

Plaid Identity Verification lets you verify the identity of your customers and seamlessly stitches together verification methods. Using Identity Verification, you can verify identification documents, phone numbers, name, date of birth, ID numbers, addresses, and more. Identity Verification also integrates directly with Monitor for an end-to-end verification and KYC solution.

image of Plaid Link Identity Verification UI

Plaid Identity Verification can also be used together with Plaid Identity in a single workflow to provide full identity verification and fraud reduction. Identity Verification is used to verify that the user of your app is the person they claim to be, while Identity is used to confirm that the ownership information on their linked bank or credit card account matches this verified identity.

Identity Verification can be used to verify end users in any country. To integrate with Identity Verification, your company must be based in the US or Canada (support for additional countries coming soon).

Identity Verification checks

Plaid offers a variety of verification checks to choose from. You can combine multiple verification checks within a single Identity Verification template via the Workflow Management editor, and even run certain checks conditionally, such as only running a particular verification if another verification fails, or running different checks based on your user's country of origin.

Lightning Verification

Lightning Verification verifies a user's name, address, date of birth, phone number, and ID number (such as SSN) against available records. You can configure the level of matching required for each field in your template’s Identity Rules. The results of this check will be summarized in the kyc_check object in the API.

Document Verification

Document Verification prompts the user to upload an image of an identity document. Plaid will use anti-fraud checks to verify that the document appears to be legitimate and is unexpired. Plaid will also verify the date of birth and name on the document against the data provided by the user. You can review and configure which document types are supported for each country.

Selfie Check

When Selfie Check is enabled, the user will be asked to take a selfie as part of the verification process. Plaid will verify that the selfie submitted is a live video of a real human. If Document Verification is enabled, Selfie Check will also verify that the selfie matches the photo in the document.

SMS Verification

SMS Verification will verify a user's phone number by asking them to enter a code sent via SMS.

AML Screening

If you're also using Monitor, AML Screening allows you to screen a user against government watchlists during an IDV session by incorporating one of your Monitor screening programs into an IDV template.

Risk Check

Plaid automatically runs anti-fraud checks in the background of a user’s verification session and summarizes the results into several categories. The data collected in each category is analyzed and assigned a risk level. Whether the overall risk check passes or fails is determined by the template’s Risk Rules, which you can configure.

Identity Verification integration process

Access to Identity Verification in the Sandbox test environment is not provided by default. To obtain Sandbox access, request product access from the Dashboard.

The steps below explain how to set up the standard Identity Verification flow. For details on other flow options, including the backend-only flow and hosted UI flow, see Integration options for Identity Verification.

Note that unlike other Plaid products, which are configured primarily via the API, most options for Identity Verification are configured on the web, via the Template Editor within the Identity Verification Dashboard. Detailed documentation on configuring Identity Verification templates is available via in-app help within the Template Editor. To request access to the Template Editor and Identity Verification Dashboard, contact your Plaid Account Manager, or file a Product Access request.

  1. Visit the Plaid dashboard and, in the upper-left corner, select Identity Verification and Monitor from the team selection drop-down list. If you don't see this option, you may need to talk to your Plaid Account Manager and ask them to enable this product for you, or file a Product access request.
  2. Under Identity Verification, select or create the template you want to use, click the Integration button, and copy the template_id.
    • (Optional) If you plan to integrate with Monitor, enable the Screening Program option and select the appropriate Monitor program.
  3. (Optional) Call /identity_verification/create if you already have information about your user that you can fill out on their behalf. See pre-populating user information for more details.
  4. Call /link/token/create. In addition to the required parameters, you will need to provide the following:
    • For identity_verification.template_id, use the template_id you copied in step 2.
    • For products, use ["identity_verification"]. Identity Verification is mutually exclusive with other products.
    • Provide user.client_user_id and optionally user.email_address. See below for details on these fields.
  5. On your web or mobile client, create an instance of Link using the link_token returned by /link/token/create; for more details, see the Link documentation.
  6. When the user has successfully completed the client-side Link flow, you will receive an onSuccess callback and be able to review the session in the dashboard.
  7. To retrieve the status of your user's verification attempt, make a call to /identity_verification/get, passing in the verification session ID. You can retrieve this session ID from the metadata in the Link callbacks, from the /identity_verification/create response, or from the Identity Verification webhooks that Plaid sends during the process.
  8. You can retrieve a list of all of your user's verification attempts by making a call to /identity_verification/list, passing in the client_user_id and the template_id.
Events and callbacks

You can optionally track the progress of users through the Link flow via client-side callbacks and events. For more information, see Link callbacks.

Mobile support

Identity Verification is fully supported by Plaid's mobile SDKs. Because the end user may need to use the camera during the Identity Verification flow, your app must request certain permissions in order to fully support Identity Verification flows on mobile. For more details, see the documentation for the Android and iOS SDKs.

Client User Id

The mandatory client_user_id field should be a unique and persistent identifier for your customer, such as the id field on your users table.

Identity Verification intelligently handles sessions being started with the same client_user_id multiple times. If your customer starts a Link session, closes it, reopens it, and reopens your Link integration, their session will resume from where they left off. Likewise, if your customer has completed their Link session in the past (by either failing verification or passing), Plaid will not serve them another session unless you've manually authorized another attempt from the dashboard or made a call to /identity_verification/retry.

Plaid indexes the client_user_id you provide, allowing you to look up users using your internal id.

If you do not want to expose your internal id to Plaid directly, you can symmetrically encrypt the identifier with a secret key that only your servers know.

Supplementing with email

During /link/token/create, Identity Verification accepts email_address as an optional additional parameter. While the field is optional, we highly recommend providing it. Identity Verification will include the user's email in the Link session and perform a number of anti-fraud related checks, including analyzing social networks, abusive emails, and email address trustworthiness.

Integration options for Identity Verification

Identity Verification offers several options for streamlined flows.

Streamlining Link by pre-populating user information (hybrid Link flow)

If you already know some information about your user (such as their name, phone number, or address), you can simplify the verification process by making a call to /identity_verification/create, passing in any information you know about your user, including their client_user_id. When you open up a Link session against this same client_user_id, Identity Verification can make use of the information that you passed in. Any fields or screens requesting information you already provided will be skipped (not shown) in the UI. For data format specifications, see Hybrid Input Validation.

Lightning Checks without UI (backend flow)

If you have already obtained a user's information and their consent to share it with Plaid, and do not need interactive capabilities such as Document Check, Selfie Check, or SMS verification, you can bypass the Identity Verification UI entirely and run an entirely programmatic verification:

  1. Create a template that requires only Lightning (KYC) check and does not use SMS verification.
  2. Call /identity_verification/create with all the user data required by this template and gave_consent: true.
  3. Call /identity_verification/get with the id returned by /identity_verification/create to retrieve the status of the verification.
Verification links (hosted flow)

Identity Verification offers the option to generate Plaid-hosted verification links. These links can be used in scenarios where your user signed up for your service outside of an app or website -- for example if a user is opening a bank account or applying for a loan in person at a brick-and-mortar retail location. To generate a verification link, click Create verification from the Identity Verification template view in the dashboard. Alternatively, you can call /identity_verification/create with is_shareable: true; a verification link will be returned in the shareable_url field of the response. Once you have shared the verification link, the user can open the link and complete the verification on their phone or other device.

Auto-fill

When auto-fill is enabled, Plaid will use the user's phone number and date of birth to attempt to auto-fill other fields. The user will be asked to confirm their auto-filled information is accurate before submitting. Auto-fill can only be enabled when using SMS Verification and Lightning Verification and is only available for US verifications.

Retries

If you want to give a user another attempt to verify their identity -- for example, if they failed verification due to a typo -- you can issue them a retry. This can be done from the dashboard when reviewing a verification by clicking Request Retry and selecting the steps to include, or via API by calling /identity_verification/retry with their client_user_id, template_id, and the strategy you want to use.

Retries can be issued from any verification check. Any steps included in the retry will be reset and cleared of any PII entered by the user or passed via API in previous verification attempts. Lightning data can be passed programmatically for a retry by calling /identity_verification/retry and passing the user’s data in the user object. /identity_verification/create should only be used to create an initial session for users who have never been verified before.

Each retry will generate a new session_id, with the same client_user_id and template_id used in the original session. Retries will use the most recent version of the template, which may be different from the version used in the original verification session.

Financial Account Matching

If you are a customer of Identity, you can seamlessly compare a user's financial accounts with their Identity Verification profile. When a user verifies their identity and links their accounts with Plaid, we detect if they are linking a bank account that belongs to them. In the Plaid Dashboard, you’ll see "match" scores against the account owner’s name, email, phone number, and address.

To turn on this feature, you will need to enable it in the template editor and call /identity/get or /identity/match with the same client_user_id that was used for Identity Verification.

Supported languages

Identity Verification currently supports flows in English, French, Spanish, Japanese, and Portuguese. Link will attempt to auto-detect the correct language based on the user's browser settings. Users can also manually change the language of their session through a dropdown in the Link UI. Unlike other Plaid products, Identity Verification does not use the language setting in /link/token/create.

Testing Identity Verification

For more information about testing Identity Verification in Sandbox, see Testing Identity Verification.

Sample app and additional resources

For a sample integration, see the Identity Verification Quickstart on GitHub.

For a step-by-step walkthrough of implementing Identity Verification, see the Identity Verification and Monitor solution guide

Next steps

To learn more about building with Identity Verification, see the Identity Verification API Reference.

If you're ready to launch to Production, see the Launch checklist.

virtual accounts managing virtual accounts

Managing your Virtual Account

Set up, control, and monitor virtual account activity

By default, you are able to create virtual accounts in Sandbox. Start by calling /wallet/create. In order to use virtual accounts in Production, contact your Account Manager.

Accessing Virtual Account details

To fetch virtual account details, use /wallet/get or /wallet/list.

Fund your Virtual Account

You can top up your virtual account in two ways: a manual bank transfer or Payment Initiation. In Sandbox, virtual accounts must be funded using Payment Initiation.

To fund a virtual account via a manual bank transfer, initiate a transfer from your bank account by specifying the virtual account numbers as the transaction's recipient.

To fund a virtual account via Payment Initiation, follow the typical Payment Initiation flow. Use the recipient_id associated with your wallet_id so Plaid knows to route the payment to your virtual account.

Webhooks

An overview of webhooks at Plaid is available in the API Reference. There you can find general information on Plaid webhooks, including IP addresses, webhook verification, and retry logic.

To get status updates on all transaction activity in the virtual account, set up a webhook listener endpoint via the Plaid Dashboard. Use the Wallet transaction event type with your webhook URL. Plaid will fire the WALLET_TRANSACTION_STATUS_UPDATE webhook to alert you when there are any changes to the status of a transaction.

Reconciling transactions

To reconcile transactions:

  1. Call the /wallet/transaction/get or /wallet/transaction/list endpoint for the virtual account you want to pull transactions for.

  2. Cross-check the received transaction IDs with your stored transactions and compare the transaction statuses to ensure they are up to date. If the stored status is different, update it with the transaction status from the /wallet/transaction/get or /wallet/transaction/list endpoint in Step 1.

Plaid supports the transaction types linked here.

Valid transaction statuses for each transaction type are outlined below.

Credit transactions

Credit transaction types: PIS_PAY_IN and BANK_TRANSFER

Status     Terminal  Valid transitions  Description
INITIATEDNoSETTLED, FAILEDThe transaction has been initiated.
SETTLEDYesThe transaction has settled in the virtual account.
FAILEDYesThe transaction could not be executed, for example, due to an invalid recipient or invalid reference.
Debit transactions

Debit transactions types: PAYOUT and REFUND

Status     Terminal  Valid transitions  Description
AUTHORISINGNoINITIATED, FAILED, BLOCKEDThe transaction is being processed for validation and compliance.
INITIATEDNoEXECUTED, FAILEDThe transaction passed authorisation checks and is being processed by the payment network.
EXECUTEDYesThe transaction has been successfully executed. Plaid does not have visibility into the settlement of debit transactions in the destination account. A transaction will typically settle within seconds to several days, depending on which payment rail is used. On rare occasions, a transaction may fail to settle after being executed, for example, if it is rejected by the payment rails due to compliance or anti-money-laundering checks.
FAILEDYesThe transaction failed, for example, due to an invalid recipient or invalid reference.
BLOCKEDYesThe transaction was blocked due to compliance checks and could not be executed.

Idempotency

An idempotency key is a unique value generated by you that allows Plaid to identify subsequent retries of the same request. A unique idempotency key should be generated for each different request. An idempotency key should be re-used only when retrying an existing request. You can choose how to create unique keys. We suggest using either V4 UUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys can be up to 128 characters long.

Idempotency keys are valid for 24 hours after the first request. After 24 hours, any request reusing a previously-used idempotency key will be treated as a new request. When two requests with the same idempotency key, within 24 hours, have a different payload, the request will result in an error.

The idempotency_key is required for the /wallet/transaction/execute and /payment_initiation/payment/reverse endpoints as it allows users to safely retry failed requests without creating a duplicate transaction. By providing the same idempotency_key for the same request, no more than one transaction is created.

auth partnerships fortress trust

Add Fortress Trust to your app

Use Fortress Trust with Plaid Auth to send and receive payments!

Partnership Fortress Trust logo

Overview

Plaid and Fortress Trust have partnered to enable integrating clients to pass end client banking data into the Fortress ecosystem via a seamlessly encrypted token, using the Plaid Processor Token. This enables a secure transfer of account information for integrators to be able to execute ACH transfers into and out of the Fortress Trust ecosystem for fiat to cryptocurrency on/off ramps, payments, and Trust custody solutions.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Fortress Trust account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Fortress Trust processor_token, which allows you to quickly and securely verify a bank funding source via Fortress Trust's API without having to store any sensitive banking information. Utilizing Plaid + Fortress Trust enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Fortress Trust in order to use the Plaid + Fortress Trust integration. You'll also need to enable your Plaid account for the Fortress Trust integration.

First, you will need to work with the Fortress Trust team to sign up for a Fortress Trust account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Fortress Trust to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Fortress Trust processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Fortress Trust, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Fortress Trust processor_token. You'll send this token to Fortress Trust and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Fortress Trust processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'fortress_trust',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Fortress Trust Production credentials prior to initiating live payment transactions in the Fortress Trust API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

link android android v2 migration

1.x to 2.x Migration Guide

Reference for migrating the Link Android SDK from 1.x to 2.x

Overview

The 2.x release is an overhaul of the SDK's API to simplify integration and align it with the iOS SDK.

  • The content provider is no longer necessary. Instead, call Plaid.initialize(application) to initialize the SDK
  • PlaidOptions has been removed, instead pass environment and logLevel in your LinkConfiguration
  • The PlaidLinkResultHandler no longer requires a request code
  • The onCancelled callback has been removed, all exit events will be returned in onExit
  • Adds support for Account Subtype filtering
  • Kotlin functions have been added for a more semantic API
  • Several object and field names have been adjusted

For an example demonstrating how to migrate from the 1.x to 2.x SDK, see a sample migration on GitHub.

link update mode

Updating Items via Link

Use update mode to add permissions to Items, or to resolve ITEM_LOGIN_REQUIRED or PAYMENT_PROFILE_LOGIN_REQUIRED statuses

image of Plaid Link update mode flow

When to use update mode

Update mode is used to update authentication or authorization for an Item. The most common reason for this is when access to an existing Item stops working: if the end user changes a password, if multi-factor authentication (MFA) requirements change, or if the login becomes locked. An Item can also require its authentication to be refreshed with update mode if it was only authorized for a limited amount of time and the authorization has expired or is nearing expiration, which can happen to Items from institutions that use OAuth flows in Plaid Link.

Update mode can also be used to request permission to access data that the user did not originally grant during the initial link flow. This can include specific OAuth permissions, or access to new accounts or additional product scopes. Update mode can be used to manage permissions granted via OAuth, as well as permissions granted directly through Plaid via Account Select or the opt-in Data Transparency Messaging beta.

Beginning in April 2023, existing Items at institutions that use OAuth, that are not currently using Account Select v2, will use Account Select v2 when the update mode flow is completed for that Item.

Resolving ITEM_LOGIN_REQUIRED or PENDING_EXPIRATION errors

Receiving an ITEM_LOGIN_REQUIRED error or a PENDING_EXPIRATION webhook indicates that the Item should be re-initialized via update mode.

If you receive the ITEM_LOGIN_REQUIRED error after calling a Plaid endpoint, implement Link in update mode during the user flow, and ask the user to re-authenticate before proceeding to the next step in your flow.

If you receive the ITEM_LOGIN_REQUIRED error via the ITEM: ERROR webhook, or if you receive the PENDING_EXPIRATION webhook, re-authenticate with Link in update mode when the user is next in your app. You will need to tell your user (using in-app messaging and/or notifications such as email or text message) to return to your app to fix their Item.

When resolving these errors, for most institutions, Plaid will present an abbreviated re-authentication flow requesting only the minimum user input required to repair the Item. For example, if the Item entered an error state because the user's OTP token expired, the user may be prompted to provide another OTP token, but not to fully re-login to the institution.

Resolving PAYMENT_PROFILE_LOGIN_REQUIRED authorization decision rationale

Receiving the PAYMENT_PROFILE_LOGIN_REQUIRED authorization decision rationale from the /transfer/authorization/create response indicates that the bank login for this Payment Profile has expired.

Ask the user to re-authenticate with Link in Payment Profile update mode, which will prompt the user to re-login and return the Payment Profile into a good state for subsequent transfers.

Requesting additional permissions

Update mode can also be used to collect additional permissions.

If using Account Select v2, you can use update mode to request your users to share new accounts with you. Receiving a NEW_ACCOUNTS_AVAILABLE webhook indicates that Plaid has detected new accounts that you may want to ask your users to share.

If using Data Transparency Messaging, update mode can be used to request permissions for additional product scopes.

Triggering update mode for an OAuth institution will cause the user to re-enter the OAuth flow. They can then grant any required OAuth permissions they failed to grant originally, or restore OAuth permissions they may have revoked. The update mode flow for OAuth institutions will also contain guidance recommending which permissions the user should grant: for more details, see the OAuth documentation.

When an Item is sent through update mode, users can also choose to revoke access they had previously granted. If you lose access to necessary accounts or OAuth permissions after the user completes the update mode flow, you may need to send the user through update mode again. For more details, see Managing consent revocation.

Using update mode

To use update mode for an Item, initialize Link with a link_token configured with the access_token for the Item that you wish to update. Note that no products should be specified when creating a link_token for update mode, unless you are using update mode to add Assets or Income. You can obtain a link_token using the /link/token/create endpoint.

If you're using update mode to refresh an OAuth institution, ensure you configure the Link token with a redirect URI, as described in Configure your Link token with your redirect URI.

Select group for content switcher
Select Language
1// Create a one-time use link_token for the Item.
2// This link_token can be used to initialize Link
3// in update mode for the user
4const configs = {
5  user: {
6    client_user_id: 'UNIQUE_USER_ID',
7  },
8  client_name: 'Your App Name Here',
9  country_codes: [CountryCode.Us],
10  language: 'en',
11  webhook: 'https://webhook.sample.com',
12  access_token: 'ENTER_YOUR_ACCESS_TOKEN_HERE',
13};
14app.post('/create_link_token', async (request, response, next) => {
15  const linkTokenResponse = await client.linkTokenCreate(configs);
16
17  // Use the link_token to initialize Link
18  response.json({ link_token: linkTokenResponse.data.link_token });
19});

Link auto-detects the appropriate institution and handles the credential and multi-factor authentication process, if needed.

An Item's access_token does not change when using Link in update mode, so there is no need to repeat the exchange token process.

1// Initialize Link with the token parameter
2// set to the generated link_token for the Item
3const linkHandler = Plaid.create({
4  token: 'GENERATED_LINK_TOKEN',
5  onSuccess: (public_token, metadata) => {
6    // You do not need to repeat the /item/public_token/exchange
7    // process when a user uses Link in update mode.
8    // The Item's access_token has not changed.
9  },
10  onExit: (err, metadata) => {
11    // The user exited the Link flow.
12    if (err != null) {
13      // The user encountered a Plaid API error prior
14      // to exiting.
15    }
16    // metadata contains the most recent API request ID and the
17    // Link session ID. Storing this information is helpful
18    // for support.
19  },
20});

Link will automatically detect the institution ID associated with the link_token and present the appropriate credential view to your user.

If your integration is still using a public_token to open Link in update mode, see the migration guide to upgrade to link_tokens. You can also see the maintenance guide to troubleshoot any public_token issues.

When an Item is restored from the ITEM_LOGIN_REQUIRED state via update mode, if it has been initialized with a product that sends Item webhooks (such as Transactions or Investments), the next webhook fired for the Item will include data for all missed information back to the last time Plaid made a successful connection to the Item.

Using update mode to request new accounts

You can allow end users to add new accounts to an Item by enabling Account Select when initializing Link in update mode. To do so, first initialize Link for update mode by creating a link_token using the /link/token/create endpoint. For OAuth institutions, ensure you configure the Link token with a redirect URI, as described in Configure your Link token with your redirect URI.

In addition, make sure you specify the following:

  1. The update.account_selection_enabled flag set to true. To ensure you are able to use this flag, check that your Plaid library meets the minimum version required.

  2. A link_customization_name for a customization that enables Account Select v2. The settings on this customization will determine which View Behavior for the Account Select pane is shown in update flow.

  3. (Optional) Any account_filters to specify account filtering. Note that this field cannot be set for update mode if account selection isn’t enabled. Once your user has updated their account selection, all selected accounts will be shared in the accounts field in the onSuccess() callback from Link. Any de-selected accounts will no longer be shared with you. You will only be able to receive data for these accounts the user selects in update mode going forward.

This update mode flow can also be used to remove accounts from an Item. We recommend that you remove any data associated with accounts that your user has de-selected. Note that Chase is an exception to the ability to remove accounts via update mode; to remove access to a specific account on a Chase Item, the end user must do so through the online Chase Security Center.

1curl -X POST https://sandbox.plaid.com/link/token/create \
2-H 'Content-Type: application/json' \
3-d '{
4  "client_id": "CLIENT_ID",
5  "secret": "SECRET",
6  "client_name": "My App",
7  "user": { "client_user_id": "UNIQUE_USER_ID" },
8  "country_codes": ["US"],
9  "language": "en",
10  "webhook": "https://webhook.sample.com",
11  "access_token": "ENTER_YOUR_ACCESS_TOKEN",
12  "link_customization_name": "account_selection_v2_customization",
13  "update": { "account_selection_enabled": true }
14}'

When using the Assets product specifically, if a user selects additional accounts during update mode but does not successfully complete the Link flow, Assets authorization will be revoked from the Item. If this occurs, have the user go through a new Link flow in order to generate an Asset Report, or, if you have Data Transparency Messaging enabled, use update mode to re-authorize the Item for assets, as described in the next section.

Using update mode to request additional consent for products

You will need to use update mode to request additional consent for products in the following situations: if you are adding Assets or Income, or if you are using Data Transparency Messaging.

Because Assets and Income may be used for underwriting use cases, they require additional user consent. To add Assets or Income to an Item that did not previously have those products enabled, you will need to send the user through update mode.

The process to do this is the same as described in Using update mode, except that you will also include the products array in the request with the value assets or income for the product you wish to add.

If the user connected their account less than two years ago, they can bypass the Link credentials pane and complete just the consent panes. Otherwise, they will be prompted to complete the full flow.

If you have Data Transparency Messaging enabled, you need user consent to access new products. To do so, first initialize Link for update mode by creating a link_token using the /link/token/create endpoint. For OAuth institutions, ensure you configure the Link token with a redirect URI, as described in Configure your Link token with your redirect URI.

In addition, make sure you specify the following:

  • The additional_consented_products field should be set to include any new products you want to gather consent for.
    • For example, if Link was initialized with just Transactions and you want to upgrade to Identity, you would pass in identity to the additional_consented_products field.
    • To see the currently authorized and consented products on an Item, use the /item/get endpoint
  • The link_customization_name should be set to a customization with Data Transparency Messaging enabled. The use case string should also be broadened to include your reasons for accessing the new data. If the use case is not customized, the default use case will be present on the Data Transparency Messaging pane.

If the upgrade was successful, you will receive the onSuccess() callback and you will have access to the API endpoints for all of the products you passed into Link update mode. The new products will only be billed once the related API endpoints are called, even if they would otherwise be billed upon Item initialization (e.g., Transactions).

Using update mode for Payment Profiles

To use update mode for Transfer's Payment Profile, initialize Link by creating a link_token using the /link/token/create endpoint with transfer.payment_profile_token configured for the Payment Profile you intend to update.

In addition, make sure you specify the following:

  • The products field should not be supplied.
  • The user object should have no phone number field supplied.
1curl -X POST https://sandbox.plaid.com/link/token/create \
2-H 'Content-Type: application/json' \
3-d '{
4  "client_id": "CLIENT_ID",
5  "secret": "SECRET",
6  "client_name": "My App",
7  "user": { "client_user_id": "UNIQUE_USER_ID" },
8  "country_codes": ["US"],
9  "language": "en",
10  "transfer": { "payment_profile_token": "PAYMENT_PROFILE_TOKEN" }
11}'

Payment Profile update mode will prompt the user to log in to their financial institution in order to re-authenticate their previously linked account. If the user does not complete the Payment Profile update mode flow, you will have to create a new Payment Profile for the user.

After the user successfully logs back in, you can call /transfer/authorization/create to determine transfer failure risk.

Testing update mode

Update mode can be tested in the Sandbox using the /sandbox/item/reset_login endpoint, which will force a given Item into an ITEM_LOGIN_REQUIRED state.

Testing Payment Profile update mode

Transfer specific Payment Profile update mode can be tested in Sandbox using the /sandbox/payment_profile/reset_login endpoint, which will force a Payment Profile into a state where the login is no longer valid. Subsequent calls with the Payment Profile to /transfer/authorization/create will result in the PAYMENT_PROFILE_LOGIN_REQUIRED decision rationale getting returned.

Example React code in Plaid Pattern

For a real-life example that illustrates the handling of update mode, see linkTokens.js and LaunchLink.tsx. These files contain the Link update mode code for the React-based Plaid Pattern sample app.

Related errors and rationale

Below is a list of errors that you may encounter in update mode or that may cause you to launch the update mode flow:

  • ITEM_LOGIN_REQUIRED – This error suggest the financial institution indicated that the user's password or MFA information has changed. They will need to reauthenticate via Link's update mode.
  • INVALID_UPDATED_USERNAME – This error indicates the username associated with an item is no longer valid.
  • PAYMENT_PROFILE_LOGIN_REQUIRED - This rationale indicates that the financial institution login for the Payment Profile is expired.

Account selection screens in update mode

To demonstrate the user experience of various update mode flows, below are screenshots of update mode that correspond to different Account Select V2 settings.

auth partnerships unit

Add Unit to your app

Use Unit with Plaid Auth to send and receive payments!

Partnership Unit logo

Overview

Plaid and Unit have partnered to help Unit clients instantly authenticate external bank accounts and subsequently interact with them as counterparties within Unit. The integration helps Unit clients easily fund accounts on Unit, pull funds from counterparties, or push funds to counterparties without requiring them to handle their account details.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Unit account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Unit processor_token, which allows you to quickly and securely verify a bank funding source via Unit's API without having to store any sensitive banking information. Utilizing Plaid + Unit enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Unit in order to use the Plaid + Unit integration. You'll also need to enable your Plaid account for the Unit integration.

First, you will need to work with the Unit team to sign up for a Unit account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Unit to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Unit processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Unit, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Unit processor_token. You'll send this token to Unit and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Unit processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'unit',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Unit Production credentials prior to initiating live payment transactions in the Unit API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

api products assets

Assets

API reference for Assets endpoints and webhooks

Create, delete, retrieve and share Asset Reports with information about a user's assets and transactions.

Endpoints
/asset_report/createCreate an Asset Report
/asset_report/getGet an Asset Report
/asset_report/pdf/getGet a PDF Asset Report
/asset_report/refreshCreate an updated Asset Report
/asset_report/filterFilter unneeded accounts from an Asset Report
/asset_report/removeDelete an asset report
/asset_report/audit_copy/createCreate an Audit Copy of an Asset Report for sharing
/asset_report/audit_copy/removeDelete an Audit Copy of an Asset Report
/credit/relay/createCreate a relay token of an Asset Report for sharing (beta)
/credit/relay/getRetrieve the report associated with a relay token (beta)
/credit/relay/refreshRefresh a report of a relay token (beta)
/credit/relay/removeDelete a relay token (beta)
Webhooks
PRODUCT_READYAsset Report generation has completed
ERRORAsset Report generation has failed

Endpoints

/asset_report/create

Create an Asset Report

The /asset_report/create endpoint initiates the process of creating an Asset Report, which can then be retrieved by passing the asset_report_token return value to the /asset_report/get or /asset_report/pdf/get endpoints.
The Asset Report takes some time to be created and is not available immediately after calling /asset_report/create. The exact amount of time to create the report will vary depending on how many days of history are requested and will typically range from a few seconds to about one minute. When the Asset Report is ready to be retrieved using /asset_report/get or /asset_report/pdf/get, Plaid will fire a PRODUCT_READY webhook. For full details of the webhook schema, see Asset Report webhooks.
The /asset_report/create endpoint creates an Asset Report at a moment in time. Asset Reports are immutable. To get an updated Asset Report, use the /asset_report/refresh endpoint.

asset_report/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_tokens
[string]
An array of access tokens corresponding to the Items that will be included in the report. The assets product must have been initialized for the Items during link; the Assets product cannot be added after initialization.

Min items: 1
Max items: 99
days_requested
requiredinteger
The maximum integer number of days of history to include in the Asset Report. If using Fannie Mae Day 1 Certainty, days_requested must be at least 61 for new originations or at least 31 for refinancings.
An Asset Report requested with "Additional History" (that is, with more than 61 days of transaction history) will incur an Additional History fee.

Maximum: 731
Minimum: 0
options
object
An optional object to filter /asset_report/create results. If provided, must be non-null. The optional user object is required for the report to be eligible for Fannie Mae's Day 1 Certainty program.
client_report_id
string
Client-generated identifier, which can be used by lenders to track loan applications.
webhook
string
URL to which Plaid will send Assets webhooks, for example when the requested Asset Report is ready.
add_ons
[string]
Use this field to request a fast_asset report. When Fast Assets is requested, Plaid will create two versions of the Asset Report: first, the Fast Asset Report, which will contain only current identity and balance information, and later, the Full Asset Report, which will also contain historical balance information and transaction data. A PRODUCT_READY webhook will be fired for each Asset Report when it is ready, and the report_type field will indicate whether the webhook is firing for the full or fast Asset Report. To retrieve the Fast Asset Report, call /asset_report/get with fast_report set to true. There is no additional charge for using Fast Assets.

Possible values: investments, fast_assets
user
object
The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The first_name, last_name, and ssn fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program.
client_user_id
string
An identifier you determine and submit for the user.
first_name
string
The user's first name. Required for the Fannie Mae Day 1 Certainty™ program.
middle_name
string
The user's middle name
last_name
string
The user's last name. Required for the Fannie Mae Day 1 Certainty™ program.
ssn
string
The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program.
Format: "ddd-dd-dddd"
phone_number
string
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis.
email
string
The user's email address.
Select group for content switcher
Select Language
1const daysRequested = 60;
2const options = {
3  client_report_id: '123',
4  webhook: 'https://www.example.com',
5  user: {
6    client_user_id: '7f57eb3d2a9j6480121fx361',
7    first_name: 'Jane',
8    middle_name: 'Leah',
9    last_name: 'Doe',
10    ssn: '123-45-6789',
11    phone_number: '(555) 123-4567',
12    email: 'jane.doe@example.com',
13  },
14};
15const request: AssetReportCreateRequest = {
16  access_tokens: [accessToken],
17  days_requested,
18  options,
19};
20// accessTokens is an array of Item access tokens.
21// Note that the assets product must be enabled for all Items.
22// All fields on the options object are optional.
23try {
24  const response = await plaidClient.assetReportCreate(request);
25  const assetReportId = response.data.asset_report_id;
26  const assetReportToken = response.data.asset_report_token;
27} catch (error) {
28  // handle error
29}
asset_report/create

Response fields and example

asset_report_token
string
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
asset_report_id
string
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "asset_report_token": "assets-sandbox-6f12f5bb-22dd-4855-b918-f47ec439198a",
3  "asset_report_id": "1f414183-220c-44f5-b0c8-bc0e6d4053bb",
4  "request_id": "Iam3b"
5}
Was this helpful?

/asset_report/get

Retrieve an Asset Report

The /asset_report/get endpoint retrieves the Asset Report in JSON format. Before calling /asset_report/get, you must first create the Asset Report using /asset_report/create (or filter an Asset Report using /asset_report/filter) and then wait for the PRODUCT_READY webhook to fire, indicating that the Report is ready to be retrieved.
By default, an Asset Report includes transaction descriptions as returned by the bank, as opposed to parsed and categorized by Plaid. You can also receive cleaned and categorized transactions, as well as additional insights like merchant name or location information. We call this an Asset Report with Insights. An Asset Report with Insights provides transaction category, location, and merchant information in addition to the transaction strings provided in a standard Asset Report. To retrieve an Asset Report with Insights, call /asset_report/get endpoint with include_insights set to true.
If report_type was set to VERIFICATION_OF_EMPLOYMENT when the Asset Report was created in /asset_report/create, debit transactions and transaction amounts won’t be included in the report.
For latency-sensitive applications, you can optionally call /asset_report/create with options.add_ons set to ["fast_assets"]. This will cause Plaid to create two versions of the Asset Report: one with only current and available balance and identity information, and then later on the complete Asset Report. You will receive separate webhooks for each version of the Asset Report.

asset_report/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
asset_report_token
string
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
include_insights
boolean
true if you would like to retrieve the Asset Report with Insights, false otherwise. This field defaults to false if omitted.

Default: false
fast_report
boolean
true to fetch "fast" version of asset report. Defaults to false if omitted. Can only be used if /asset_report/create was called with options.add_ons set to ["fast_assets"].

Default: false
options
object
An optional object to filter or add data to /asset_report/get results. If provided, must be non-null.
days_to_include
integer
The maximum number of days of history to include in the Asset Report.

Maximum: 731
Minimum: 0
Select group for content switcher
Select Language
1const request: request = {
2  asset_report_token: assetReportToken,
3  include_insights: true,
4};
5try {
6  const response = await plaidClient.assetReportGet(request);
7  const assetReportId = response.data.asset_report_id;
8} catch (error) {
9  if (error.data.error_code == 'PRODUCT_NOT_READY') {
10    // Asset report is not ready yet. Try again later
11  } else {
12    // handle error
13  }
14}
asset_report/get

Response fields and example

report
object
An object representing an Asset Report
asset_report_id
string
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.
client_report_id
nullablestring
An identifier you determine and submit for the Asset Report.
date_generated
string
The date and time when the Asset Report was created, in ISO 8601 format (e.g. "2018-04-12T03:32:11Z").

Format: date-time
days_requested
number
The duration of transaction history you requested
user
object
The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The first_name, last_name, and ssn fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program.
client_user_id
nullablestring
An identifier you determine and submit for the user.
first_name
nullablestring
The user's first name. Required for the Fannie Mae Day 1 Certainty™ program.
middle_name
nullablestring
The user's middle name
last_name
nullablestring
The user's last name. Required for the Fannie Mae Day 1 Certainty™ program.
ssn
nullablestring
The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program.
Format: "ddd-dd-dddd"
phone_number
nullablestring
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis.
email
nullablestring
The user's email address.
items
[object]
Data returned by Plaid about each of the Items included in the Asset Report.
item_id
string
The item_id of the Item associated with this webhook, warning, or error
institution_name
string
The full financial institution name associated with the Item.
institution_id
string
The id of the financial institution associated with the Item.
date_last_updated
string
The date and time when this Item’s data was last retrieved from the financial institution, in ISO 8601 format.

Format: date-time
accounts
[object]
Data about each of the accounts open on the Item.
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullablenumber
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullablenumber
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullablenumber
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullablestring
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
days_available
number
The duration of transaction history available for this Item, typically defined as the time since the date of the earliest transaction in that account.
transactions
[object]
Transaction history associated with the account.
account_id
string
The ID of the account in which this transaction occurred.
amount
number
The settled value of the transaction, denominated in the transaction's currency, as stated in iso_currency_code or unofficial_currency_code. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the transaction. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the transaction. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
original_description
nullablestring
The string returned by the financial institution to describe the transaction.
category
nullable[string]
A hierarchical array of the categories to which this transaction belongs. For a full list of categories, see /categories/get.
This field will only appear in an Asset Report with Insights.
category_id
nullablestring
The ID of the category to which this transaction belongs. For a full list of categories, see /categories/get.
This field will only appear in an Asset Report with Insights.
credit_category
nullableobject
Information describing the intent of the transaction. Most relevant for credit use cases, but not limited to such use cases. Please reach out to your account manager or sales representative if you would like to receive this field.
See the taxonomy csv file for a full list of credit categories.
primary
string
A high level category that communicates the broad category of the transaction.
detailed
string
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.
check_number
nullablestring
The check number of the transaction. This field is only populated for check transactions.
date
string
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ).

Format: date
date_transacted
nullablestring
The date on which the transaction took place, in IS0 8601 format.
location
object
A representation of where a transaction took place
address
nullablestring
The street address where the transaction occurred.
city
nullablestring
The city where the transaction occurred.
region
nullablestring
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.
postal_code
nullablestring
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code where the transaction occurred.
lat
nullablenumber
The latitude where the transaction occurred.

Format: double
lon
nullablenumber
The longitude where the transaction occurred.

Format: double
store_number
nullablestring
The merchant defined store number where the transaction occurred.
name
string
The merchant name or transaction description.
This field will only appear in an Asset Report with Insights.
merchant_name
nullablestring
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.
payment_meta
object
Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null.
If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, the payment_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
reference_number
nullablestring
The transaction reference number supplied by the financial institution.
ppd_id
nullablestring
The ACH PPD ID for the payer.
payee
nullablestring
For transfers, the party that is receiving the transaction.
by_order_of
nullablestring
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.
payer
nullablestring
For transfers, the party that is paying the transaction.
payment_method
nullablestring
The type of transfer, e.g. 'ACH'
payment_processor
nullablestring
The name of the payment processor
reason
nullablestring
The payer-supplied description of the transfer.
pending
boolean
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.
pending_transaction_id
nullablestring
The ID of a posted transaction's associated pending transaction, where applicable.
account_owner
nullablestring
The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts.
transaction_id
string
The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive.
transaction_type
string
digital: transactions that took place online.
place: transactions that were made at a physical location.
special: transactions that relate to banks, e.g. fees or deposits.
unresolved: transactions that do not fit into the other three types.

Possible values: digital, place, special, unresolved
owners
[object]
Data returned by the financial institution about the account owner or owners.For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution. Multiple owners on a single account will be represented in the same owner object, not in multiple owner objects within the array. In API versions 2018-05-22 and earlier, the owners object is not returned, and instead identity information is returned in the top level identity object. For more details, see Plaid API versioning
names
[string]
A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders.
If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.
phone_numbers
[object]
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
string
The phone number.
primary
boolean
When true, identifies the phone number as the primary number on an account.
type
string
The type of phone number.

Possible values: home, work, office, mobile, mobile1, other
emails
[object]
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
string
The email address.
primary
boolean
When true, identifies the email address as the primary email on an account.
type
string
The type of email account as described by the financial institution.

Possible values: primary, secondary, other
addresses
[object]
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
object
Data about the components comprising an address.
city
nullablestring
The full city name
region
nullablestring
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
nullablestring
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code
primary
boolean
When true, identifies the address as the primary address on an account.
ownership_type
nullablestring
How an asset is owned.
association: Ownership by a corporation, partnership, or unincorporated association, including for-profit and not-for-profit organizations. individual: Ownership by an individual. joint: Joint ownership by multiple parties. trust: Ownership by a revocable or irrevocable trust.

Possible values: null, individual, joint, association, trust
historical_balances
[object]
Calculated data about the historical balances on the account.
date
string
The date of the calculated historical balance, in an ISO 8601 format (YYYY-MM-DD)

Format: date
current
number
The total amount of funds in the account, calculated from the current balance in the balance object by subtracting inflows and adding back outflows according to the posted date of each transaction.
If the account has any pending transactions, historical balance amounts on or after the date of the earliest pending transaction may differ if retrieved in subsequent Asset Reports as a result of those pending transactions posting.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null.
See the currency code schema for a full listing of supported unofficial_currency_codes.
warnings
[object]
If the Asset Report generation was successful but identity information cannot be returned, this array will contain information about the errors causing identity information to be missing
warning_type
string
The warning type, which will always be ASSET_REPORT_WARNING
warning_code
string
The warning code identifies a specific kind of warning. OWNERS_UNAVAILABLE indicates that account-owner information is not available.INVESTMENTS_UNAVAILABLE indicates that Investments specific information is not available. TRANSACTIONS_UNAVAILABLE indicates that transactions information associated with Credit and Depository accounts are unavailable.

Possible values: OWNERS_UNAVAILABLE, INVESTMENTS_UNAVAILABLE, TRANSACTIONS_UNAVAILABLE
cause
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
item_id
string
The item_id of the Item associated with this webhook, warning, or error
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "report": {
3    "asset_report_id": "028e8404-a013-4a45-ac9e-002482f9cafc",
4    "client_report_id": "client_report_id_1221",
5    "date_generated": "2023-03-30T18:27:37Z",
6    "days_requested": 5,
7    "items": [
8      {
9        "accounts": [
10          {
11            "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8",
12            "balances": {
13              "available": 43200,
14              "current": 43200,
15              "iso_currency_code": "USD",
16              "unofficial_currency_code": null,
17              "limit": null
18            },
19            "days_available": 5,
20            "historical_balances": [
21              {
22                "current": 49050,
23                "date": "2023-03-29",
24                "iso_currency_code": "USD",
25                "unofficial_currency_code": null
26              },
27              {
28                "current": 49050,
29                "date": "2023-03-28",
30                "iso_currency_code": "USD",
31                "unofficial_currency_code": null
32              },
33              {
34                "current": 49050,
35                "date": "2023-03-27",
36                "iso_currency_code": "USD",
37                "unofficial_currency_code": null
38              },
39              {
40                "current": 49050,
41                "date": "2023-03-26",
42                "iso_currency_code": "USD",
43                "unofficial_currency_code": null
44              },
45              {
46                "current": 49050,
47                "date": "2023-03-25",
48                "iso_currency_code": "USD",
49                "unofficial_currency_code": null
50              }
51            ],
52            "mask": "4444",
53            "name": "Plaid Money Market",
54            "official_name": "Plaid Platinum Standard 1.85% Interest Money Market",
55            "owners": [
56              {
57                "addresses": [
58                  {
59                    "data": {
60                      "city": "Malakoff",
61                      "country": "US",
62                      "region": "NY",
63                      "street": "2992 Cameron Road",
64                      "postal_code": "14236"
65                    },
66                    "primary": true
67                  },
68                  {
69                    "data": {
70                      "city": "San Matias",
71                      "country": "US",
72                      "region": "CA",
73                      "street": "2493 Leisure Lane",
74                      "postal_code": "93405-2255"
75                    },
76                    "primary": false
77                  }
78                ],
79                "emails": [
80                  {
81                    "data": "accountholder0@example.com",
82                    "primary": true,
83                    "type": "primary"
84                  },
85                  {
86                    "data": "accountholder1@example.com",
87                    "primary": false,
88                    "type": "secondary"
89                  },
90                  {
91                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
92                    "primary": false,
93                    "type": "other"
94                  }
95                ],
96                "names": [
97                  "Alberta Bobbeth Charleson"
98                ],
99                "phone_numbers": [
100                  {
101                    "data": "1112223333",
102                    "primary": false,
103                    "type": "home"
104                  },
105                  {
106                    "data": "1112224444",
107                    "primary": false,
108                    "type": "work"
109                  },
110                  {
111                    "data": "1112225555",
112                    "primary": false,
113                    "type": "mobile"
114                  }
115                ]
116              }
117            ],
118            "ownership_type": null,
119            "subtype": "money market",
120            "transactions": [
121              {
122                "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8",
123                "amount": 5850,
124                "date": "2023-03-30",
125                "iso_currency_code": "USD",
126                "original_description": "ACH Electronic CreditGUSTO PAY 123456",
127                "pending": false,
128                "transaction_id": "gGQgjoeyqBF89PND6K14Sow1wddZBmtLomJ78",
129                "unofficial_currency_code": null
130              }
131            ],
132            "type": "depository"
133          },
134          {
135            "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
136            "balances": {
137              "available": 100,
138              "current": 110,
139              "iso_currency_code": "USD",
140              "unofficial_currency_code": null,
141              "limit": null
142            },
143            "days_available": 5,
144            "historical_balances": [
145              {
146                "current": 110,
147                "date": "2023-03-29",
148                "iso_currency_code": "USD",
149                "unofficial_currency_code": null
150              },
151              {
152                "current": -390,
153                "date": "2023-03-28",
154                "iso_currency_code": "USD",
155                "unofficial_currency_code": null
156              },
157              {
158                "current": -373.67,
159                "date": "2023-03-27",
160                "iso_currency_code": "USD",
161                "unofficial_currency_code": null
162              },
163              {
164                "current": -284.27,
165                "date": "2023-03-26",
166                "iso_currency_code": "USD",
167                "unofficial_currency_code": null
168              },
169              {
170                "current": -284.27,
171                "date": "2023-03-25",
172                "iso_currency_code": "USD",
173                "unofficial_currency_code": null
174              }
175            ],
176            "mask": "0000",
177            "name": "Plaid Checking",
178            "official_name": "Plaid Gold Standard 0% Interest Checking",
179            "owners": [
180              {
181                "addresses": [
182                  {
183                    "data": {
184                      "city": "Malakoff",
185                      "country": "US",
186                      "region": "NY",
187                      "street": "2992 Cameron Road",
188                      "postal_code": "14236"
189                    },
190                    "primary": true
191                  },
192                  {
193                    "data": {
194                      "city": "San Matias",
195                      "country": "US",
196                      "region": "CA",
197                      "street": "2493 Leisure Lane",
198                      "postal_code": "93405-2255"
199                    },
200                    "primary": false
201                  }
202                ],
203                "emails": [
204                  {
205                    "data": "accountholder0@example.com",
206                    "primary": true,
207                    "type": "primary"
208                  },
209                  {
210                    "data": "accountholder1@example.com",
211                    "primary": false,
212                    "type": "secondary"
213                  },
214                  {
215                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
216                    "primary": false,
217                    "type": "other"
218                  }
219                ],
220                "names": [
221                  "Alberta Bobbeth Charleson"
222                ],
223                "phone_numbers": [
224                  {
225                    "data": "1112223333",
226                    "primary": false,
227                    "type": "home"
228                  },
229                  {
230                    "data": "1112224444",
231                    "primary": false,
232                    "type": "work"
233                  },
234                  {
235                    "data": "1112225555",
236                    "primary": false,
237                    "type": "mobile"
238                  }
239                ]
240              }
241            ],
242            "ownership_type": null,
243            "subtype": "checking",
244            "transactions": [
245              {
246                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
247                "amount": 89.4,
248                "date": "2023-03-27",
249                "iso_currency_code": "USD",
250                "original_description": "SparkFun",
251                "pending": false,
252                "transaction_id": "4zBRq1Qem4uAPnoyKjJNTRQpQddM4ztlo1PLD",
253                "unofficial_currency_code": null
254              },
255              {
256                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
257                "amount": 12,
258                "date": "2023-03-28",
259                "iso_currency_code": "USD",
260                "original_description": "McDonalds #3322",
261                "pending": false,
262                "transaction_id": "dkjL41PnbKsPral79jpxhMWdW55gkPfBkWpRL",
263                "unofficial_currency_code": null
264              },
265              {
266                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
267                "amount": 4.33,
268                "date": "2023-03-28",
269                "iso_currency_code": "USD",
270                "original_description": "Starbucks",
271                "pending": false,
272                "transaction_id": "a84ZxQaWDAtDL3dRgmazT57K7jjN3WFkNWMDy",
273                "unofficial_currency_code": null
274              },
275              {
276                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
277                "amount": -500,
278                "date": "2023-03-29",
279                "iso_currency_code": "USD",
280                "original_description": "United Airlines **** REFUND ****",
281                "pending": false,
282                "transaction_id": "xG9jbv3eMoFWepzB7wQLT3LoLggX5Duy1Gbe5",
283                "unofficial_currency_code": null
284              }
285            ],
286            "type": "depository"
287          }
288        ],
289        "date_last_updated": "2023-03-30T18:25:26Z",
290        "institution_id": "ins_109508",
291        "institution_name": "First Platypus Bank",
292        "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7"
293      }
294    ],
295    "user": {
296      "client_user_id": "uid_40332",
297      "email": "abcharleston@example.com",
298      "first_name": "Anna",
299      "last_name": "Charleston",
300      "middle_name": "B",
301      "phone_number": "1-415-867-5309",
302      "ssn": "111-22-1234"
303    }
304  },
305  "request_id": "GVzMdiDd8DDAQK4",
306  "warnings": []
307}
Was this helpful?

/asset_report/pdf/get

Retrieve a PDF Asset Report

The /asset_report/pdf/get endpoint retrieves the Asset Report in PDF format. Before calling /asset_report/pdf/get, you must first create the Asset Report using /asset_report/create (or filter an Asset Report using /asset_report/filter) and then wait for the PRODUCT_READY webhook to fire, indicating that the Report is ready to be retrieved.
The response to /asset_report/pdf/get is the PDF binary data. The request_id is returned in the Plaid-Request-ID header.
If report_type was set to VERIFICATION_OF_EMPLOYMENT when the Asset Report was created in /asset_report/create, debit transactions and transaction amounts won’t be included in the report.
View a sample PDF Asset Report.

asset_report/pdf/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
asset_report_token
requiredstring
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
options
object
An optional object to filter or add data to /asset_report/get results. If provided, must be non-null.
days_to_include
integer
The maximum integer number of days of history to include in the Asset Report.

Maximum: 731
Minimum: 0
Select group for content switcher
Select Language
1try {
2  const request: AssetReportPDFGetRequest = {
3    asset_report_token: assetReportToken,
4  };
5  const response = await plaidClient.assetReportPdfGet(request, {
6    responseType: 'arraybuffer',
7  });
8  const pdf = response.buffer.toString('base64');
9} catch (error) {
10  // handle error
11}
Response

This endpoint returns binary PDF data. View a sample Asset Report PDF.

Was this helpful?

/asset_report/refresh

Refresh an Asset Report

An Asset Report is an immutable snapshot of a user's assets. In order to "refresh" an Asset Report you created previously, you can use the /asset_report/refresh endpoint to create a new Asset Report based on the old one, but with the most recent data available.
The new Asset Report will contain the same Items as the original Report, as well as the same filters applied by any call to /asset_report/filter. By default, the new Asset Report will also use the same parameters you submitted with your original /asset_report/create request, but the original days_requested value and the values of any parameters in the options object can be overridden with new values. To change these arguments, simply supply new values for them in your request to /asset_report/refresh. Submit an empty string ("") for any previously-populated fields you would like set as empty.

asset_report/refresh

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
asset_report_token
requiredstring
The asset_report_token returned by the original call to /asset_report/create
days_requested
integer
The maximum number of days of history to include in the Asset Report. Must be an integer. If not specified, the value from the original call to /asset_report/create will be used.

Minimum: 0
Maximum: 731
options
object
An optional object to filter /asset_report/refresh results. If provided, cannot be null. If not specified, the options from the original call to /asset_report/create will be used.
client_report_id
string
Client-generated identifier, which can be used by lenders to track loan applications.
webhook
string
URL to which Plaid will send Assets webhooks, for example when the requested Asset Report is ready.
user
object
The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The first_name, last_name, and ssn fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program.
client_user_id
string
An identifier you determine and submit for the user.
first_name
string
The user's first name. Required for the Fannie Mae Day 1 Certainty™ program.
middle_name
string
The user's middle name
last_name
string
The user's last name. Required for the Fannie Mae Day 1 Certainty™ program.
ssn
string
The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program.
Format: "ddd-dd-dddd"
phone_number
string
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis.
email
string
The user's email address.
Select group for content switcher
Select Language
1const request: AssetReportRefreshRequest = {
2  asset_report_token: assetReportToken,
3  daysRequested: 60,
4  options: {
5    client_report_id: '123',
6    webhook: 'https://www.example.com',
7    user: {
8      client_user_id: '7f57eb3d2a9j6480121fx361',
9      first_name: 'Jane',
10      middle_name: 'Leah',
11      last_name: 'Doe',
12      ssn: '123-45-6789',
13      phone_number: '(555) 123-4567',
14      email: 'jane.doe@example.com',
15    },
16  },
17};
18try {
19  const response = await plaidClient.assetReportRefresh(request);
20  const assetReportId = response.data.asset_report_id;
21} catch (error) {
22  // handle error
23}
asset_report/refresh

Response fields and example

asset_report_id
string
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.
asset_report_token
string
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "asset_report_id": "c33ebe8b-6a63-4d74-a83d-d39791231ac0",
3  "asset_report_token": "assets-sandbox-8218d5f8-6d6d-403d-92f5-13a9afaa4398",
4  "request_id": "NBZaq"
5}
Was this helpful?

/asset_report/filter

Filter Asset Report

By default, an Asset Report will contain all of the accounts on a given Item. In some cases, you may not want the Asset Report to contain all accounts. For example, you might have the end user choose which accounts are relevant in Link using the Account Select view, which you can enable in the dashboard. Or, you might always exclude certain account types or subtypes, which you can identify by using the /accounts/get endpoint. To narrow an Asset Report to only a subset of accounts, use the /asset_report/filter endpoint.
To exclude certain Accounts from an Asset Report, first use the /asset_report/create endpoint to create the report, then send the asset_report_token along with a list of account_ids to exclude to the /asset_report/filter endpoint, to create a new Asset Report which contains only a subset of the original Asset Report's data.
Because Asset Reports are immutable, calling /asset_report/filter does not alter the original Asset Report in any way; rather, /asset_report/filter creates a new Asset Report with a new token and id. Asset Reports created via /asset_report/filter do not contain new Asset data, and are not billed.
Plaid will fire a PRODUCT_READY webhook once generation of the filtered Asset Report has completed.

asset_report/filter

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
asset_report_token
requiredstring
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
account_ids_to_exclude
required[string]
The accounts to exclude from the Asset Report, identified by account_id.
Select group for content switcher
Select Language
1const request: AssetReportFilterRequest = {
2  asset_report_token: assetReportToken,
3  account_ids_to_exclude: ['JJGWd5wKDgHbw6yyzL3MsqBAvPyDlqtdyk419'],
4};
5try {
6  const response = await plaidClient.assetReportFilter(request);
7  const assetReportId = response.data.asset_report_id;
8} catch (error) {
9  // handle error
10}
asset_report/filter

Response fields and example

asset_report_token
string
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
asset_report_id
string
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "asset_report_token": "assets-sandbox-bc410c6a-4653-4c75-985c-e757c3497c5c",
3  "asset_report_id": "fdc09207-0cef-4d88-b5eb-0d970758ebd9",
4  "request_id": "qEg07"
5}
Was this helpful?

/asset_report/remove

Delete an Asset Report

The /item/remove endpoint allows you to invalidate an access_token, meaning you will not be able to create new Asset Reports with it. Removing an Item does not affect any Asset Reports or Audit Copies you have already created, which will remain accessible until you remove them specifically.
The /asset_report/remove endpoint allows you to remove an Asset Report. Removing an Asset Report invalidates its asset_report_token, meaning you will no longer be able to use it to access Report data or create new Audit Copies. Removing an Asset Report does not affect the underlying Items, but does invalidate any audit_copy_tokens associated with the Asset Report.

asset_report/remove

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
asset_report_token
requiredstring
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
Select group for content switcher
Select Language
1const request: AssetReportRemoveRequest = {
2  asset_report_token: assetReportToken,
3};
4try {
5  const response = await plaidClient.assetReportRemove(request);
6  const removed = response.data.removed;
7} catch (error) {
8  // handle error
9}
asset_report/remove

Response fields and example

removed
boolean
true if the Asset Report was successfully removed.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "removed": true,
3  "request_id": "I6zHN"
4}
Was this helpful?

/asset_report/audit_copy/create

Create Asset Report Audit Copy

Plaid can provide an Audit Copy of any Asset Report directly to a participating third party on your behalf. For example, Plaid can supply an Audit Copy directly to Fannie Mae on your behalf if you participate in the Day 1 Certainty™ program. An Audit Copy contains the same underlying data as the Asset Report.
To grant access to an Audit Copy, use the /asset_report/audit_copy/create endpoint to create an audit_copy_token and then pass that token to the third party who needs access. Each third party has its own auditor_id, for example fannie_mae. You’ll need to create a separate Audit Copy for each third party to whom you want to grant access to the Report.

asset_report/audit_copy/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
asset_report_token
requiredstring
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
auditor_id
string
The auditor_id of the third party with whom you would like to share the Asset Report.
Select group for content switcher
Select Language
1// The auditor ID corresponds to the third party with which you want to share
2// the asset report. For example, Fannie Mae's auditor ID is 'fannie_mae'.
3const request: AssetReportAuditCopyCreateRequest = {
4  asset_report_token: createResponse.data.asset_report_token,
5  auditor_id: 'fannie_mae',
6};
7try {
8  const response = await plaidClient.assetReportAuditCopyCreate(request);
9  const auditCopyToken = response.data.audit_copy_token;
10} catch (error) {
11  // handle error
12}
asset_report/audit_copy/create

Response fields and example

audit_copy_token
string
A token that can be shared with a third party auditor to allow them to obtain access to the Asset Report. This token should be stored securely.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "audit_copy_token": "a-sandbox-3TAU2CWVYBDVRHUCAAAI27ULU4",
3  "request_id": "Iam3b"
4}
Was this helpful?

/asset_report/audit_copy/remove

Remove Asset Report Audit Copy

The /asset_report/audit_copy/remove endpoint allows you to remove an Audit Copy. Removing an Audit Copy invalidates the audit_copy_token associated with it, meaning both you and any third parties holding the token will no longer be able to use it to access Report data. Items associated with the Asset Report, the Asset Report itself and other Audit Copies of it are not affected and will remain accessible after removing the given Audit Copy.

asset_report/audit_copy/remove

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
audit_copy_token
requiredstring
The audit_copy_token granting access to the Audit Copy you would like to revoke.
Select group for content switcher
Select Language
1// auditCopyToken is the token from the createAuditCopy response.
2const request: AssetReportAuditCopyRemoveRequest = {
3  audit_copy_token: auditCopyToken,
4};
5try {
6  const response = await plaidClient.assetReportAuditCopyRemove(request);
7  const removed = response.data.removed;
8} catch (error) {
9  // handle error
10}
asset_report/audit_copy/remove

Response fields and example

removed
boolean
true if the Audit Copy was successfully removed.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "removed": true,
3  "request_id": "m8MDnv9okwxFNBV"
4}
Was this helpful?

/credit/relay/create

Create a relay token to share an Asset Report with a partner client (beta)

Plaid can share an Asset Report directly with a participating third party on your behalf. The shared Asset Report is the exact same Asset Report originally created in /asset_report/create.
To grant a third party access to an Asset Report, use the /credit/relay/create endpoint to create a relay_token and then pass that token to your third party. Each third party has its own secondary_client_id; for example, ce5bd328dcd34123456. You'll need to create a separate relay_token for each third party that needs access to the report on your behalf.

credit/relay/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
report_tokens
required[string]
List of report token strings, with at most one token of each report type. Currently only Asset Report token is supported.
secondary_client_id
requiredstring
The secondary_client_id is the client id of the third party with whom you would like to share the relay token.
webhook
string
URL to which Plaid will send webhooks when the Secondary Client successfully retrieves an Asset Report by calling /credit/relay/get.
Select Language
1const request: CreditRelayCreateRequest = {
2  report_tokens: [createResponse.data.asset_report_token],
3};
4try {
5  const response = await plaidClient.creditRelayCreate(request);
6  const relayToken = response.data.relay_token;
7} catch (error) {
8  // handle error
9}
credit/relay/create

Response fields and example

relay_token
string
A token that can be shared with a third party to allow them to access the Asset Report. This token should be stored securely.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "relay_token": "credit-relay-production-3TAU2CWVYBDVRHUCAAAI27ULU4",
3  "request_id": "Iam3b"
4}
Was this helpful?

/credit/relay/get

Retrieve the reports associated with a relay token that was shared with you (beta)

/credit/relay/get allows third parties to receive a report that was shared with them, using a relay_token that was created by the report owner.

credit/relay/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
relay_token
requiredstring
The relay_token granting access to the report you would like to get.
report_type
requiredstring
The report type. It can be assets or income.

Possible values: assets, income
Select Language
1const request: CreditRelayGetRequest = {
2  relay_token: createResponse.data.relay_token,
3  report_type: 'assets',
4};
5try {
6  const response = await plaidClient.creditRelayGet(request);
7} catch (error) {
8  // handle error
9}
credit/relay/get

Response fields and example

report
object
An object representing an Asset Report
asset_report_id
string
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.
client_report_id
nullablestring
An identifier you determine and submit for the Asset Report.
date_generated
string
The date and time when the Asset Report was created, in ISO 8601 format (e.g. "2018-04-12T03:32:11Z").

Format: date-time
days_requested
number
The duration of transaction history you requested
user
object
The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The first_name, last_name, and ssn fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program.
client_user_id
nullablestring
An identifier you determine and submit for the user.
first_name
nullablestring
The user's first name. Required for the Fannie Mae Day 1 Certainty™ program.
middle_name
nullablestring
The user's middle name
last_name
nullablestring
The user's last name. Required for the Fannie Mae Day 1 Certainty™ program.
ssn
nullablestring
The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program.
Format: "ddd-dd-dddd"
phone_number
nullablestring
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis.
email
nullablestring
The user's email address.
items
[object]
Data returned by Plaid about each of the Items included in the Asset Report.
item_id
string
The item_id of the Item associated with this webhook, warning, or error
institution_name
string
The full financial institution name associated with the Item.
institution_id
string
The id of the financial institution associated with the Item.
date_last_updated
string
The date and time when this Item’s data was last retrieved from the financial institution, in ISO 8601 format.

Format: date-time
accounts
[object]
Data about each of the accounts open on the Item.
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullablenumber
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullablenumber
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullablenumber
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullablestring
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
days_available
number
The duration of transaction history available for this Item, typically defined as the time since the date of the earliest transaction in that account.
transactions
[object]
Transaction history associated with the account.
account_id
string
The ID of the account in which this transaction occurred.
amount
number
The settled value of the transaction, denominated in the transaction's currency, as stated in iso_currency_code or unofficial_currency_code. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the transaction. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the transaction. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
original_description
nullablestring
The string returned by the financial institution to describe the transaction.
category
nullable[string]
A hierarchical array of the categories to which this transaction belongs. For a full list of categories, see /categories/get.
This field will only appear in an Asset Report with Insights.
category_id
nullablestring
The ID of the category to which this transaction belongs. For a full list of categories, see /categories/get.
This field will only appear in an Asset Report with Insights.
credit_category
nullableobject
Information describing the intent of the transaction. Most relevant for credit use cases, but not limited to such use cases. Please reach out to your account manager or sales representative if you would like to receive this field.
See the taxonomy csv file for a full list of credit categories.
primary
string
A high level category that communicates the broad category of the transaction.
detailed
string
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.
check_number
nullablestring
The check number of the transaction. This field is only populated for check transactions.
date
string
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ).

Format: date
date_transacted
nullablestring
The date on which the transaction took place, in IS0 8601 format.
location
object
A representation of where a transaction took place
address
nullablestring
The street address where the transaction occurred.
city
nullablestring
The city where the transaction occurred.
region
nullablestring
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.
postal_code
nullablestring
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code where the transaction occurred.
lat
nullablenumber
The latitude where the transaction occurred.

Format: double
lon
nullablenumber
The longitude where the transaction occurred.

Format: double
store_number
nullablestring
The merchant defined store number where the transaction occurred.
name
string
The merchant name or transaction description.
This field will only appear in an Asset Report with Insights.
merchant_name
nullablestring
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.
payment_meta
object
Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null.
If the transactions object was returned by a Transactions endpoint such as /transactions/sync or /transactions/get, the payment_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
reference_number
nullablestring
The transaction reference number supplied by the financial institution.
ppd_id
nullablestring
The ACH PPD ID for the payer.
payee
nullablestring
For transfers, the party that is receiving the transaction.
by_order_of
nullablestring
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.
payer
nullablestring
For transfers, the party that is paying the transaction.
payment_method
nullablestring
The type of transfer, e.g. 'ACH'
payment_processor
nullablestring
The name of the payment processor
reason
nullablestring
The payer-supplied description of the transfer.
pending
boolean
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.
pending_transaction_id
nullablestring
The ID of a posted transaction's associated pending transaction, where applicable.
account_owner
nullablestring
The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts.
transaction_id
string
The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive.
transaction_type
string
digital: transactions that took place online.
place: transactions that were made at a physical location.
special: transactions that relate to banks, e.g. fees or deposits.
unresolved: transactions that do not fit into the other three types.

Possible values: digital, place, special, unresolved
owners
[object]
Data returned by the financial institution about the account owner or owners.For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution. Multiple owners on a single account will be represented in the same owner object, not in multiple owner objects within the array. In API versions 2018-05-22 and earlier, the owners object is not returned, and instead identity information is returned in the top level identity object. For more details, see Plaid API versioning
names
[string]
A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders.
If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.
phone_numbers
[object]
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
string
The phone number.
primary
boolean
When true, identifies the phone number as the primary number on an account.
type
string
The type of phone number.

Possible values: home, work, office, mobile, mobile1, other
emails
[object]
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
string
The email address.
primary
boolean
When true, identifies the email address as the primary email on an account.
type
string
The type of email account as described by the financial institution.

Possible values: primary, secondary, other
addresses
[object]
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
object
Data about the components comprising an address.
city
nullablestring
The full city name
region
nullablestring
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
nullablestring
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code
primary
boolean
When true, identifies the address as the primary address on an account.
ownership_type
nullablestring
How an asset is owned.
association: Ownership by a corporation, partnership, or unincorporated association, including for-profit and not-for-profit organizations. individual: Ownership by an individual. joint: Joint ownership by multiple parties. trust: Ownership by a revocable or irrevocable trust.

Possible values: null, individual, joint, association, trust
historical_balances
[object]
Calculated data about the historical balances on the account.
date
string
The date of the calculated historical balance, in an ISO 8601 format (YYYY-MM-DD)

Format: date
current
number
The total amount of funds in the account, calculated from the current balance in the balance object by subtracting inflows and adding back outflows according to the posted date of each transaction.
If the account has any pending transactions, historical balance amounts on or after the date of the earliest pending transaction may differ if retrieved in subsequent Asset Reports as a result of those pending transactions posting.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null.
See the currency code schema for a full listing of supported unofficial_currency_codes.
warnings
[object]
If the Asset Report generation was successful but identity information cannot be returned, this array will contain information about the errors causing identity information to be missing
warning_type
string
The warning type, which will always be ASSET_REPORT_WARNING
warning_code
string
The warning code identifies a specific kind of warning. OWNERS_UNAVAILABLE indicates that account-owner information is not available.INVESTMENTS_UNAVAILABLE indicates that Investments specific information is not available. TRANSACTIONS_UNAVAILABLE indicates that transactions information associated with Credit and Depository accounts are unavailable.

Possible values: OWNERS_UNAVAILABLE, INVESTMENTS_UNAVAILABLE, TRANSACTIONS_UNAVAILABLE
cause
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
item_id
string
The item_id of the Item associated with this webhook, warning, or error
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "report": {
3    "asset_report_id": "bf3a0490-344c-4620-a219-2693162e4b1d",
4    "client_report_id": "123abc",
5    "date_generated": "2020-06-05T22:47:53Z",
6    "days_requested": 3,
7    "items": [
8      {
9        "accounts": [
10          {
11            "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
12            "balances": {
13              "available": 200,
14              "current": 210,
15              "iso_currency_code": "USD",
16              "limit": null,
17              "unofficial_currency_code": null
18            },
19            "days_available": 3,
20            "historical_balances": [
21              {
22                "current": 210,
23                "date": "2020-06-04",
24                "iso_currency_code": "USD",
25                "unofficial_currency_code": null
26              },
27              {
28                "current": 210,
29                "date": "2020-06-03",
30                "iso_currency_code": "USD",
31                "unofficial_currency_code": null
32              },
33              {
34                "current": 210,
35                "date": "2020-06-02",
36                "iso_currency_code": "USD",
37                "unofficial_currency_code": null
38              }
39            ],
40            "mask": "1111",
41            "name": "Plaid Saving",
42            "official_name": "Plaid Silver Standard 0.1% Interest Saving",
43            "owners": [
44              {
45                "addresses": [
46                  {
47                    "data": {
48                      "city": "Malakoff",
49                      "country": "US",
50                      "postal_code": "14236",
51                      "region": "NY",
52                      "street": "2992 Cameron Road"
53                    },
54                    "primary": true
55                  },
56                  {
57                    "data": {
58                      "city": "San Matias",
59                      "country": "US",
60                      "postal_code": "93405-2255",
61                      "region": "CA",
62                      "street": "2493 Leisure Lane"
63                    },
64                    "primary": false
65                  }
66                ],
67                "emails": [
68                  {
69                    "data": "accountholder0@example.com",
70                    "primary": true,
71                    "type": "primary"
72                  },
73                  {
74                    "data": "accountholder1@example.com",
75                    "primary": false,
76                    "type": "secondary"
77                  },
78                  {
79                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
80                    "primary": false,
81                    "type": "other"
82                  }
83                ],
84                "names": [
85                  "Alberta Bobbeth Charleson"
86                ],
87                "phone_numbers": [
88                  {
89                    "data": "1112223333",
90                    "primary": false,
91                    "type": "home"
92                  },
93                  {
94                    "data": "1112224444",
95                    "primary": false,
96                    "type": "work"
97                  },
98                  {
99                    "data": "1112225555",
100                    "primary": false,
101                    "type": "mobile"
102                  }
103                ]
104              }
105            ],
106            "ownership_type": null,
107            "subtype": "savings",
108            "transactions": [],
109            "type": "depository"
110          },
111          {
112            "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
113            "balances": {
114              "available": null,
115              "current": 56302.06,
116              "iso_currency_code": "USD",
117              "limit": null,
118              "unofficial_currency_code": null
119            },
120            "days_available": 3,
121            "historical_balances": [],
122            "mask": "8888",
123            "name": "Plaid Mortgage",
124            "official_name": null,
125            "owners": [
126              {
127                "addresses": [
128                  {
129                    "data": {
130                      "city": "Malakoff",
131                      "country": "US",
132                      "postal_code": "14236",
133                      "region": "NY",
134                      "street": "2992 Cameron Road"
135                    },
136                    "primary": true
137                  },
138                  {
139                    "data": {
140                      "city": "San Matias",
141                      "country": "US",
142                      "postal_code": "93405-2255",
143                      "region": "CA",
144                      "street": "2493 Leisure Lane"
145                    },
146                    "primary": false
147                  }
148                ],
149                "emails": [
150                  {
151                    "data": "accountholder0@example.com",
152                    "primary": true,
153                    "type": "primary"
154                  },
155                  {
156                    "data": "accountholder1@example.com",
157                    "primary": false,
158                    "type": "secondary"
159                  },
160                  {
161                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
162                    "primary": false,
163                    "type": "other"
164                  }
165                ],
166                "names": [
167                  "Alberta Bobbeth Charleson"
168                ],
169                "phone_numbers": [
170                  {
171                    "data": "1112223333",
172                    "primary": false,
173                    "type": "home"
174                  },
175                  {
176                    "data": "1112224444",
177                    "primary": false,
178                    "type": "work"
179                  },
180                  {
181                    "data": "1112225555",
182                    "primary": false,
183                    "type": "mobile"
184                  }
185                ]
186              }
187            ],
188            "ownership_type": null,
189            "subtype": "mortgage",
190            "transactions": [],
191            "type": "loan"
192          },
193          {
194            "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
195            "balances": {
196              "available": null,
197              "current": 410,
198              "iso_currency_code": "USD",
199              "limit": null,
200              "unofficial_currency_code": null
201            },
202            "days_available": 3,
203            "historical_balances": [
204              {
205                "current": 410,
206                "date": "2020-06-04",
207                "iso_currency_code": "USD",
208                "unofficial_currency_code": null
209              },
210              {
211                "current": 410,
212                "date": "2020-06-03",
213                "iso_currency_code": "USD",
214                "unofficial_currency_code": null
215              },
216              {
217                "current": 410,
218                "date": "2020-06-02",
219                "iso_currency_code": "USD",
220                "unofficial_currency_code": null
221              }
222            ],
223            "mask": "3333",
224            "name": "Plaid Credit Card",
225            "official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
226            "owners": [
227              {
228                "addresses": [
229                  {
230                    "data": {
231                      "city": "Malakoff",
232                      "country": "US",
233                      "postal_code": "14236",
234                      "region": "NY",
235                      "street": "2992 Cameron Road"
236                    },
237                    "primary": true
238                  },
239                  {
240                    "data": {
241                      "city": "San Matias",
242                      "country": "US",
243                      "postal_code": "93405-2255",
244                      "region": "CA",
245                      "street": "2493 Leisure Lane"
246                    },
247                    "primary": false
248                  }
249                ],
250                "emails": [
251                  {
252                    "data": "accountholder0@example.com",
253                    "primary": true,
254                    "type": "primary"
255                  },
256                  {
257                    "data": "accountholder1@example.com",
258                    "primary": false,
259                    "type": "secondary"
260                  },
261                  {
262                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
263                    "primary": false,
264                    "type": "other"
265                  }
266                ],
267                "names": [
268                  "Alberta Bobbeth Charleson"
269                ],
270                "phone_numbers": [
271                  {
272                    "data": "1112223333",
273                    "primary": false,
274                    "type": "home"
275                  },
276                  {
277                    "data": "1112224444",
278                    "primary": false,
279                    "type": "work"
280                  },
281                  {
282                    "data": "1112225555",
283                    "primary": false,
284                    "type": "mobile"
285                  }
286                ]
287              }
288            ],
289            "ownership_type": null,
290            "subtype": "credit card",
291            "transactions": [],
292            "type": "credit"
293          }
294        ],
295        "date_last_updated": "2020-06-05T22:47:52Z",
296        "institution_id": "ins_3",
297        "institution_name": "Chase",
298        "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6"
299      }
300    ],
301    "user": {
302      "client_user_id": "123456789",
303      "email": "accountholder0@example.com",
304      "first_name": "Alberta",
305      "last_name": "Charleson",
306      "middle_name": "Bobbeth",
307      "phone_number": "111-222-3333",
308      "ssn": "123-45-6789"
309    }
310  },
311  "request_id": "eYupqX1mZkEuQRx",
312  "warnings": []
313}
Was this helpful?

/credit/relay/refresh

Refresh a report of a relay token (beta)

The /credit/relay/refresh endpoint allows third parties to refresh a report that was relayed to them, using a relay_token that was created by the report owner. A new report will be created with the original report parameters, but with the most recent data available based on the days_requested value of the original report.

credit/relay/refresh

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
relay_token
requiredstring
The relay_token granting access to the report you would like to refresh.
report_type
requiredstring
The report type. It can be assets or income.

Possible values: assets, income
webhook
string
The URL registered to receive webhooks when the report of a relay token has been refreshed.
Select Language
1const request: CreditRelayRefreshRequest = {
2  relay_token: createResponse.data.relay_token,
3  report_type: 'assets',
4};
5try {
6  const response = await plaidClient.CreditRelayRefresh(request);
7} catch (error) {
8  // handle error
9}
credit/relay/refresh

Response fields and example

asset_report_id
string
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "relay_token": "credit-relay-sandbox-8218d5f8-6d6d-403d-92f5-13a9afaa4398",
3  "request_id": "NBZaq",
4  "asset_report_id": "bf3a0490-344c-4620-a219-2693162e4b1d"
5}
Was this helpful?

/credit/relay/remove

Remove relay token (beta)

The /credit/relay/remove endpoint allows you to invalidate a relay_token. The third party holding the token will no longer be able to access or refresh the reports which the relay_token gives access to. The original report, associated Items, and other relay tokens that provide access to the same report are not affected and will remain accessible after removing the given relay_token.

credit/relay/remove

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
relay_token
requiredstring
The relay_token you would like to revoke.
Select Language
1const request: CreditRelayRemoveRequest = {
2  relay_token: createResponse.data.relay_token,
3};
4try {
5  const response = await plaidClient.creditRelayRemove(request);
6} catch (error) {
7  // handle error
8}
credit/relay/remove

Response fields and example

removed
boolean
true if the relay token was successfully removed.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "removed": true,
3  "request_id": "m8MDnv9okwxFNBV"
4}
Was this helpful?

Webhooks

PRODUCT_READY

Fired when the Asset Report has been generated and /asset_report/get is ready to be called. If you attempt to retrieve an Asset Report before this webhook has fired, you’ll receive a response with the HTTP status code 400 and a Plaid error code of PRODUCT_NOT_READY.

webhook_type
string
ASSETS
webhook_code
string
PRODUCT_READY
asset_report_id
string
The asset_report_id corresponding to the Asset Report the webhook has fired for.
report_type
string
The report type, indicating whether the Asset Report is a full or fast report.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "ASSETS",
3  "webhook_code": "PRODUCT_READY",
4  "asset_report_id": "47dfc92b-bba3-4583-809e-ce871b321f05",
5  "report_type": "full"
6}
Was this helpful?

ERROR

Fired when Asset Report generation has failed. The resulting error will have an error_type of ASSET_REPORT_ERROR.

webhook_type
string
ASSETS
webhook_code
string
ERROR
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
asset_report_id
string
The ID associated with the Asset Report.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "ASSETS",
3  "webhook_code": "ERROR",
4  "asset_report_id": "47dfc92b-bba3-4583-809e-ce871b321f05",
5  "error": {
6    "display_message": null,
7    "error_code": "PRODUCT_NOT_ENABLED",
8    "error_message": "the 'assets' product is not enabled for the following access tokens: access-sandbox-fb88b20c-7b74-4197-8d01-0ab122dad0bc. please ensure that 'assets' is included in the 'product' array when initializing Link and create the Item(s) again.",
9    "error_type": "ASSET_REPORT_ERROR",
10    "request_id": "m8MDnv9okwxFNBV"
11  }
12}
Was this helpful?

enrich

Introduction to Enrich

Enrich your transaction data with merchant, category, and location insights.

Explore API

Overview

Enrich makes it easy to work with transaction data generated by your own banking products or retrieved from other non-Plaid sources. Enrich brings context and meaning to your data by enriching it with detailed merchant, category, and location information. The enriched data can be used to build apps and features that help users manage their cash flow, earn rewards, and discover other financial products to help them reach their financial goals.

Prefer to learn by watching? Get an overview of how Enrich works in just 3 minutes!

Sample Enrich data

Below is an example of the enrichments Plaid can provide for a transaction.

1PURCHASE WM SUPERCENTER #1700 POWAY CAUS
1"counterparties": [{
2   "name": "Walmart",
3   "type": "merchant",
4   "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",
5   "website": "walmart.com"
6   "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM"
7 }],
8 "entity_id" : "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM",
9 "location": {
10   "address": "13425 Community Rd",
11   "city": "Poway",
12   "region": "CA",
13   "country": "US",
14   "postal_code": "92064",
15   "store_number": "1700",
16   "lat": 32.959068,
17   "lon": -117.037666
18 },
19"logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",
20"merchant_name": "Walmart",
21"payment_channel": "in store",
22"personal_finance_category": {
23  "detailed": "GENERAL_MERCHANDISE_SUPERSTORES",
24  "primary": "GENERAL_MERCHANDISE",
25},
26"personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png",
27"website": "walmart.com",

Testing Enrich

Enrich is available for use in all environments.

Sandbox: Test the integration with sample transaction data. Send a request with data from this preset list of sample transactions to receive a response.

Development: Free live usage for up to 1,000 transactions. Send Plaid your transactions and we’ll provide real enrichments.

Production: Paid usage with real enrichments for all your transactions.

When testing Enrich in Development or Production, make sure to use input data and amounts that are as realistic as possible, as all input fields, not just description, are used to analyze transactions.

For more details and best practices on testing Enrich, see the Enrich Testing Guide.

Enrich integration process

  1. Prepare your transaction data for enrichment. Plaid accepts a maximum of 100 transactions per request. For each transaction, include the description, amount, direction, iso_currency_code and id. For even higher quality results, the optional location object should also be provided if available.
  2. Call /transactions/enrich to send Plaid your transactions.
  3. Plaid will provide an API response with all available enrichments for the transactions.

income add to app

Add Income to your app

Use Income to fetch income information about your users

This guide will walk you through how to use Income to retrieve information about your users' current sources of income.

Get Plaid API keys and complete application and company profile

If you don't already have one, create a Plaid developer account. After creating your account, you can find your API keys under the Team Settings menu on the Plaid Dashboard.

You also need to complete your application profile and company profile in the Dashboard if you wish to retrieve real data in Production. The information in your profile will be shared with users of your application when they manage their connection on the Plaid Portal, and must be completed before connecting to certain institutions.

Install and initialize Plaid libraries

You can use our official server-side client libraries to connect to the Plaid API from your application:

Select group for content switcher
Select Language
1// Install via npm
2npm install --save plaid

After you've installed Plaid's client libraries, you can initialize them by passing in your client_id, secret, and the environment you wish to connect to (Sandbox, Development, or Production). This will make sure the client libraries pass along your client_id and secret with each request, and you won't need to explicitly include them in any other calls.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can obtain from the Dashboard. These code samples also demonstrate starting up a server commonly used in each framework (such as Express or Flask).

Select group for content switcher
Select Language
1// Using Express
2const express = require('express');
3const app = express();
4app.use(express.json());
5
6const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
7
8const configuration = new Configuration({
9  basePath: PlaidEnvironments.sandbox,
10  baseOptions: {
11    headers: {
12      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
13      'PLAID-SECRET': process.env.PLAID_SECRET,
14    },
15  },
16});
17
18const client = new PlaidApi(configuration);

Create a User Token

Unlike many other Plaid products, where you start by creating Items to represent user connections with individual banks, with Income you first start by creating a user_token that represents an individual user. As you add various sources of income, those will all be associated with this single user_token, which allows you to receive consolidated income from different sources by requesting an income report for that user_token.

To create a user_token, make a call to the /user/create endpoint. This endpoint requires a unique client_user_id value to represent the current user. Typically, this value is the same identifier you're using in your own application to represent the currently signed-in user. This call will return a randomly-generated string for the user_token as well as a separate user ID that Plaid includes in webhooks to represent this user.

You can only create one user_token per client_user_id. If you try to create a user_token with a client_user_id that you have previously sent to Plaid, you will receive an error.

Depending on your application, you might wish to create this user_token as soon as your user creates an account, or right before they begin the process of confirming their income data with you.

1const { IdentityGetRequest } = require('plaid');
2
3// Pull Identity data for an Item
4const request: IdentityGetRequest = {
5  access_token: accessToken,
6};
7try {
8  const response = await plaidClient.identityGet(request);
9  const identities = response.data.accounts.flatMap(
10    (account) => account.owners,
11  );
12} catch (error) {
13  // handle error
14}
15
16// The userId here represents the user's internal user ID with your
17// application
18const createUserToken = async (userId) => {
19  const response = await plaidClient.userCreate({
20    client_user_id: userId,
21  });
22  const newUserToken = response.data.user_token;
23  const userIdForWebhooks = response.data.user_id;
24  await updateUserRecordWithIncomeInfo(userId, newUserToken, userIdForWebhooks);
25};

Decide what income verification method(s) you want to support

Income supports three different ways that a user can verify their sources of income.

  • Payroll Income allows Plaid to retrieve information such as recent pay stubs and W-2 forms directly from the user's payroll provider. This tends to provide the most comprehensive data, but is dependent upon the user being able to sign in with their payroll provider.
  • Document Income allows the user to upload images of income-related documents (such as pay stubs and W-2 forms), which Plaid can scan and interpret for you.
  • Bank Income allows the user to connect with their bank to identify deposits that represent sources of income.

Depending on which methods you want to support (and it's perfectly acceptable to support all three), you will need to implement slightly different processes. While you can collect Payroll and Document Income in the same Link flow, you cannot collect Payroll or Document Income in the same Link flow as Bank Income.

Fetching Payroll or Document Income data

The process for implementing Payroll and Document Income is very similar, so we'll cover these two scenarios next.

Create a Link token for Payroll or Document Income

Plaid Link is a drop-in module that provides a secure, elegant UI flow to guide your users through the process of connecting Plaid with their financial institutions. With Income, Link can help your user search for and connect to their payroll provider as well as assist them in uploading documents.

Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the appropriate section in the Link documentation.

Before initializing Link, you will need to create a new link_token on the server side of your application. A link_token is a short-lived, single-use token that is used to authenticate your app with Link. You can create one using the /link/token/create endpoint. Then, on the client side of your application, initialize Link with the link_token that you just created.

When calling the /link/token/create endpoint, you'll include an object telling Plaid about your application as well as how to customize the Link experience. When creating a link_token for Payroll or Document Income, there are a few extra values you'll need to supply in this object:

  • You will need to pass in the user_token that you created earlier.
  • You can only list "income_verification" in the list of products
  • You will need to create an object with income_source_types set to ["payroll"] and pass that as the value for income_verification

Note that in the code sample below, in addition to passing in a user_token, we are also passing in the signed in user's ID as the user.client_user_id value. These are fundamentally different user IDs used for different purposes. The user.client_user_id value is primarily used for logging purposes and allows you to search for activity in the Plaid dashboard based on the user ID. While its value is most likely the same user ID that you passed in when creating the user_token above, they are otherwise unrelated.

1// Using Express
2
3app.post('/api/create_link_token_for_payroll_income', async function (
4  request,
5  response,
6) {
7  // Get the client_user_id by searching for the current user.
8  const clientUserId = await GetSignedInUserId();
9  // Get the Plaid user token that we stored in an earlier step
10  const userToken = await GetPlaidTokenForUser();
11  const request = {
12    user: {
13      // This should correspond to a unique id for the current user.
14      client_user_id: clientUserId,
15    },
16    client_name: 'Plaid Test App',
17    products: ['income_verification'],
18    user_token: userToken,
19    income_verification: {
20      income_source_types: ['payroll'],
21    },
22    language: 'en',
23    webhook: 'https://webhook.example.com',
24    country_codes: ['US'],
25  };
26  try {
27    const createTokenResponse = await client.linkTokenCreate(request);
28    response.json(createTokenResponse.data);
29  } catch (error) {
30    // handle error
31  }
32});

By default, a link_token created this way will allow the user to collect income information using both the Payroll and Document methods. However, in some cases you might want to permit the user to only use one of these methods. To do that, you can specify the flow_types, as in the example below.

1income_verification: {
2  income_source_types: ["payroll"],
3  payroll_income: { flow_types: ["payroll_digital_income"] },
4},
Install the Link library

You need to install the Link JavaScript library from Plaid in order to use Link in your web application.

1<head>
2  <title>Connect a bank</title>
3  <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
4</head>
Configure the client-side Link handler

To run Link, you'll first need to retrieve the link_token from the server using the call to /link/token/create described above. Then, call Plaid.create(), passing along that token alongside other callbacks you might want to define. This will return a handler that has an open method. Call that method to open up the Link UI and start the connection process.

1const linkHandler = Plaid.create({
2  token: (await $.post('/api/create_link_token_for_payroll_income')).link_token,
3  onSuccess: (public_token, metadata) => {
4    // Typically, you'd exchange the public_token for an access token.
5    // While you can still do that here, it's not strictly necessary.
6  },
7  onExit: (err, metadata) => {
8    // Optionally capture when your user exited the Link flow.
9    // Storing this information can be helpful for support.
10  },
11  onEvent: (eventName, metadata) => {
12    // Optionally capture Link flow events, streamed through
13    // this callback as your users connect an Item to Plaid.
14  },
15});
16
17linkHandler.open();

If you've had experience with other Plaid products, you're probably used to taking the public_token received from Link and exchanging it on your server for a persistent access_token. However, because Payroll and Document Income are fetched once (and don't require persistent connections with your user's bank), and all of your reports are associated with the user's user_token, there's no need to retrieve or store an access_token in this case.

Listen for webhooks

After a user has finished using Link, it may take some time before Plaid has the user's income information available for you to download. In the case of Payroll Income, this typically takes a few seconds. For Document Income, this may take several minutes. Listen for the INCOME: INCOME_VERIFICATION webhook to know when this user's data is ready.

1app.post('/server/receive_webhook', async (req, res, next) => {
2  const product = req.body.webhook_type;
3  const code = req.body.webhook_code;
4  if (product === 'INCOME' && code === 'INCOME_VERIFICATION') {
5    const plaidUserId = req.body.user_id;
6    const verificationStatus = req.body.verification_status;
7    if (verificationStatus === 'VERIFICATION_STATUS_PROCESSING_COMPLETE') {
8      await retrieveIncomeDataForUser(plaidUserId);
9    } else {
10      // Handle other cases
11    }
12  }
13  // Handle other types of webhooks
14});

The user_id value included in this webhook is the same user_id that was returned by Plaid when you first created a user_token for this user.

Fetch income data

Now that Plaid has confirmed it has finished processing this user's data, you can fetch the data by making a call to the /credit/payroll_income/get endpoint. Pass in the user_token, and Plaid will return all Payroll and Document Income sources associated with that token.

1try {
2  const response = await plaidClient.creditPayrollIncomeGet({
3    user_token: userToken,
4  });
5  const incomeData = response.data;
6  // Do something interesting with the income data here.
7} catch (error) {
8  // Handle error
9}

This call will typically return an array of items, each of which represents a connection with a payroll provider. These items, in turn, contain one or more payroll_income objects that contain detailed payroll information for the user. This can include individual pay stubs (with a full breakdown of gross pay, deductions, net pay, and more), as well as W-2 forms and all of their information. See the sample response object in the documentation for a full example of what this response might look like.

You can distinguish between income that was retrieved through Payroll Income and income that was retrieved through Document Income by looking for an account_id value on the payroll_income object. If the data was retrieved through scanning user documents, this value will be null.

Fetching Bank Income data

As an alternative to downloading income data from the user's payroll provider or W-2 forms, Plaid can also find income data in the user's bank account. Plaid will look for deposits that might be sources of income and ask the user to identify which deposits represent income that they wish to share with your application.

Create a Link token for Bank Income

Creating a link_token for Bank Income is similar to the process for creating a link_token for Payroll or Document Income. The main differences are:

  • While you still must include "income_verification" as a product, you are allowed to combine this product with other products that you might want to use with this financial institution.
  • Your income_source_types must be set to ["bank"].
  • Your income_verification object must also include a bank_income object, where you have set the value of days_requested. This is the number of days back that Plaid will search for regularly occurring deposits.

The value of days_requested should a large enough number that you find all relevant deposits, but not so large that the user gets tired waiting for Plaid to retrieve all the relevant data. We recommend 120 days as good balance between the two.

1app.post('/api/create_link_token_for_bank_income', async function (
2  request,
3  response,
4) {
5  // Get the client_user_id by searching for the current user.
6  const clientUserId = await GetSignedInUserId();
7  // Get the Plaid user token that we stored in an earlier step
8  const userToken = await GetPlaidTokenForUser();
9  const request = {
10    user: {
11      // This should correspond to a unique id for the current user.
12      client_user_id: clientUserId,
13    },
14    client_name: 'Plaid Test App',
15    products: ['income_verification', 'transactions', 'assets'],
16    user_token: userToken,
17    income_verification: {
18      income_source_types: ['bank'],
19      bank_income: { days_requested: 60 },
20    },
21    language: 'en',
22    webhook: 'https://webhook.example.com',
23    country_codes: ['US'],
24  };
25  try {
26    const createTokenResponse = await client.linkTokenCreate(request);
27    response.json(createTokenResponse.data);
28  } catch (error) {
29    // handle error
30  }
31});
Install the Link library

As described earlier, you need to install the Link JavaScript library from Plaid to use Link in your web application.

Select Language
1<head>
2  <title>Connect a bank</title>
3  <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
4</head>
Configure the client-side Link handler

Retrieve the link_token from the server, then call Plaid.create(), passing along the link_token alongside other callbacks you might want to define. This will return a handler that has an open method, which you can call to start the Link process. This is similar to the process described above, but with Bank Income you will probably want to keep the public_token and exchange it for an access_token, as described in the next step.

1const linkHandler = Plaid.create({
2  token: (await $.post('/api/create_link_token_for_bank_income')).link_token,
3  onSuccess: (public_token, metadata) => {
4    // Send the public_token to your app server.
5    $.post('/exchange_public_token', {
6      public_token: public_token,
7    });
8  },
9  onExit: (err, metadata) => {
10    // Optionally capture when your user exited the Link flow.
11    // Storing this information can be helpful for support.
12  },
13  onEvent: (eventName, metadata) => {
14    // Optionally capture Link flow events, streamed through
15    // this callback as your users connect an Item to Plaid.
16  },
17});
18
19linkHandler.open();
Retrieve metadata about the Link session

Call /credit/sessions/get in your server after receiving onSuccess, passing in the user_token that you used to create the Link token.

1try {
2  const response = await plaidClient.creditSessionsGet({
3    user_token: userRecord[FIELD_USER_TOKEN],
4  });
5  const sessionData = response.data;
6} catch (error) {
7  // Handle this error
8}

If the user has finished the Bank Income verification flow, then the most recent session will have a bank_income_result with status APPROVED.

If you are using other Plaid products such as Auth or Balance alongside Bank Income, make sure to capture the public_token from the item_add_result callback and exchange it for an access_token.

Get a persistent access token (for other products)

For the purpose of retrieving income data, you don't necessarily need an access_token. Plaid will retrieve the income data for you, and then that data will be associated with the user_token that you created when first configuring Link.

However, if you are using any other product with this financial institution (such as Transactions, Balance, or Assets), you will need to exchange your public_token for an access_token and item_id. The access_token lets you make authenticated calls to these other products in the Plaid API.

Exchanging a public_token for an access_token is as easy as calling the /item/public_token/exchange endpoint from the server-side handler. Store the access_token and item_id that get returned in a secure server-side location. Never store this information on the client.

Select group for content switcher
Select Language
1app.post('/api/exchange_public_token', async function (
2  request,
3  response,
4  next,
5) {
6  const publicToken = request.body.public_token;
7  try {
8    const response = await client.itemPublicTokenExchange({
9      public_token: publicToken,
10    });
11
12    // These values should be saved to a persistent database and
13    // associated with the currently signed-in user
14    const accessToken = response.data.access_token;
15    const itemID = response.data.item_id;
16
17    res.json({ public_token_exchange: 'complete' });
18  } catch (error) {
19    // handle error
20  }
21});

Fetch income data

You can fetch income data by calling the /credit/bank_income/get endpoint using the Plaid client library, passing in the user_token you created earlier. Note that, similar to Document or Payroll Income, this data is static -- it is a snapshot of the user's income data that was retrieved by Plaid when the user ran Link. It does not update or change over time.

By default, Plaid will only return the most recent report in its response. However, you might want to retrieve more than one report if your user has intentionally run Link multiple times. You can do this by passing an options object with a count value set to an integer.

1try {
2  const response = await plaidClient.creditBankIncomeGet({
3    user_token: userRecord[FIELD_USER_TOKEN],
4    options: {
5      count: 3,
6    },
7  });
8  const bankIncomeData = response.data;
9} catch (error) {
10  // Handle this error
11}

This call typically returns a bank_income array, which consists of a number of different objects that represent the report generated when the user ran Link. These individual reports contain an items array, which in turn contains one or more objects that represent the financial institutions associated with this report. These objects contain a bank_income_accounts array of objects, which gives you information about the individual accounts, as well as a bank_income_sources array of objects, which in turn contains the total amount of income reported, along with historical transactions about that income.

Each report also contains a bank_income_summary object, that summarizes the total bank income identified across all items in this report.

Connecting to multiple banks in the same report

Bank Income allows you to accept data from multiple banks in the same report. To enable this feature, first include enable_multiple_items: true inside the bank_income object that you pass to /link/token/create.

1const request = {
2  ...
3  income_verification: {
4    income_source_types: ['bank'],
5    bank_income: {
6      days_requested: 60,
7      enable_multiple_items: true,
8    },
9  },
10};

Then, after the user has exited Link and you receive an onSuccess or onExit callback, there will be a distinct item_add_result returned in the /credit/sessions/get response for each Item the user successfully linked. If the user has completed the Bank Income verification flow for a given Item, there will be a corresponding bank_income_result for that Item with status APPROVED.

Ensure that you call /credit/sessions/get for both onSuccess and onExit Link callbacks, as the Link callback will only reflect the state of the last Item linked.

When your user connects with multiple banks in a single Link process, you will receive each bank's data in the item array for that report when calling /credit/bank_income/get.

Although retrieving multiple items in the same report makes parsing your results easier (and is a better experience for your user), you may still wish to retrieve more than one report when calling /credit/bank_income/get in case your user forgets to add all of their banks the first time and has to run Link multiple times.

Example code

For an example of an app that incorporates Document, Payroll and Bank Income, see the React and Node-based Income Sample app. The Income Sample app is an application that uses Income and Liability data to help determine whether the user can qualify for financing on a pre-owned hoverboard. It supports the use of all three types of income data.

Implementation guide

For further guidance on implementing Income in your app, see the Income Verification Solution Guide.

Next steps

If you're ready to launch to Production, see the Launch checklist.

errors invalid request

Invalid Request Errors

Guide to troubleshooting invalid request errors

INCOMPATIBLE_API_VERSION

The request uses fields that are not compatible with the API version being used.
Common causes
  • The API endpoint was called using a public_key for authentication rather than a client_id and secret.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "INCOMPATIBLE_API_VERSION",
5 "error_message": "The public_key cannot be used for this endpoint as of version {version-date} of the API. Please use the client_id and secret instead.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_ACCOUNT_NUMBER

The provided account number was invalid.
Sample user-facing error message
Account or routing number incorrect: Check with your bank and make sure that your account and routing numbers are entered correctly
Alternative user-facing error message

Account is not checking or savings: This account is not a valid checking or savings account and does not support ACH debit. Please retry with a different account.

Common causes
  • While in the Instant Match, Automated Micro-deposit, or Same-Day Micro-deposit Link flows, the user provided an account number whose last four digits did not match the account mask of their bank account.
  • If the user entered the correct account number, Plaid may have been unable to retrieve an account mask.
  • If the user entered the correct account number, the account type associated with the account may not be a supported Auth account type.
Troubleshooting steps

If the account number was correct and the account was a supported type, please contact Plaid Support.

1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "INVALID_ACCOUNT_NUMBER",
5 "error_message": "The provided account number was invalid.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_BODY

The request body was invalid.
Common causes
  • The JSON request body was malformed.
  • The request content-type was not of type application/json. The Plaid API only accepts JSON text as the MIME media type, with UTF-8 encoding, conforming to RFC 4627.
1content-type: 'application/json'
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "INVALID_BODY",
5 "error_message": "body could not be parsed as JSON",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_CONFIGURATION

/link/token/create was called with invalid configuration settings
Common causes
  • One or more of the configuration objects provided to /link/token/create does not match the request schema for that endpoint.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "INVALID_CONFIGURATION",
5 "error_message": "please ensure that the request body is formatted correctly",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_FIELD

One or more of the request body fields were improperly formatted or an invalid type.
Common causes
  • One or more fields in the request body were invalid, malformed, or used a wrong type. The error_message field will specify the erroneous field and how to resolve the error.
  • Personally identifiable information (PII), such as an email address or phone number, was provided for a field where PII is not allowed, such as user.client_user_id.
  • An unsupported country code was used in Production. Consult the API Reference for the endpoint being used for a list of valid country codes.
  • An optional parameter was not provided in a context where it is required. For example, /accounts/balance/get was called without specifying options.min_last_updated_datetime on an Item whose institution requires that parameter to be specified.
  • The /signal/decision/report or /signal/return/report endpoints were called with a client_transaction_id for which /signal/evaluate was never called.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "INVALID_FIELD",
5 "error_message": "{{ error message is specific to the given / missing request field }}",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_HEADERS

The request was missing a required header.
Common causes
  • The request was missing a header, typically the Content-Type header.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "INVALID_HEADERS",
5 "error_message": "{{ error message is specific to the given / missing header }}",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

MISSING_FIELDS

The request was missing one or more required fields.
Common causes
  • The request body is missing one or more required fields. The error_message field will list the missing field(s).
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "MISSING_FIELDS",
5 "error_message": "the following required fields are missing: {fields}",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

NO_LONGER_AVAILABLE

The endpoint requested is not available in the API version being used.
Common causes
  • The endpoint you requested has been discontinued and no longer exists in the Plaid API.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "NO_LONGER_AVAILABLE",
5 "error_message": "This endpoint has been discontinued as of version {version-date} of the API.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

NOT_FOUND

The endpoint requested does not exist.
Common causes
  • The endpoint you requested does not exist in the Plaid API.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "NOT_FOUND",
5 "error_message": "not found",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

SANDBOX_ONLY

The requested endpoint is only available in Sandbox.
Common causes
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "SANDBOX_ONLY",
5 "error_message": "access to {api/route} is only available in the sandbox environment at https://sandbox.plaid.com/",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

UNKNOWN_FIELDS

The request included a field that is not recognized by the endpoint.
Common causes
  • The request body included one or more extraneous fields. The error_message field will list the unrecognized field(s).
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "UNKNOWN_FIELDS",
5 "error_message": "the following fields are not recognized by this endpoint: {fields}",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

auth partnerships achq

Add ACHQ to your app

Use ACHQ with Plaid Auth to send and receive payments!

Partnership ACHQ logo

Overview

Plaid and ACHQ have partnered to offer fast and secure processing of ACH transactions via the web and mobile. Use Plaid Link to instantly authenticate your customer's bank account and connect to the ACHQ API to manage payment submission, monitoring, and reconciliation all from a single endpoint. With Plaid + ACHQ companies can seamlessly onboard ACH customers, leverage same-day ACH processing for both credits and debits, and eliminate payment errors. All without your business ever touching any sensitive bank data.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified ACHQ account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a ACHQ processor_token, which allows you to quickly and securely verify a bank funding source via ACHQ's API without having to store any sensitive banking information. Utilizing Plaid + ACHQ enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and ACHQ in order to use the Plaid + ACHQ integration. You'll also need to enable your Plaid account for the ACHQ integration.

First, you will need to work with the ACHQ team to sign up for a ACHQ account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for ACHQ to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a ACHQ processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with ACHQ, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a ACHQ processor_token. You'll send this token to ACHQ and they will use it to securely retrieve account and routing numbers from Plaid.

You can create ACHQ processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'achq',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need ACHQ Production credentials prior to initiating live payment transactions in the ACHQ API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

auth partnerships atomic

Add Atomic to your app

Use Atomic with Plaid Auth to send and receive payments!

Partnership Atomic logo

Overview

Plaid and Atomic have partnered to allow you to instantly authenticate your customers' bank accounts to seamlessly fund investment accounts. Atomic's investing-as-a-service platform provides personalized investment management services that let you embed investment accounts into your services - helping to enhance your value proposition, boost retention, and grow profits while enabling your customers to build wealth with you.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Atomic account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Atomic processor_token, which allows you to quickly and securely verify a bank funding source via Atomic's API without having to store any sensitive banking information. Utilizing Plaid + Atomic enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Atomic in order to use the Plaid + Atomic integration. You'll also need to enable your Plaid account for the Atomic integration.

First, you will need to work with the Atomic team to sign up for a Atomic account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Atomic to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Atomic processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Atomic, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Atomic processor_token. You'll send this token to Atomic and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Atomic processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'atomic',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Atomic Production credentials prior to initiating live payment transactions in the Atomic API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

api tokens

Token endpoints

API reference for obtaining and managing tokens from Link

Token exchange flow

Most API calls to Plaid endpoints require an access_token. An access_token provides access to a specific Item, which is a Plaid term for a login at a financial institution.

The primary flow for obtaining a Plaid access_token works as follows:

  1. Obtain a link_token by calling /link/token/create.
  2. Initialize Link by passing in the link_token. When your user completes the Link flow, Link will pass back a public_token via the onSuccess callback. For more information on initializing and receiving data back from Link, see the Link documentation.
  3. Exchange the public_token for an access_token by calling /item/public_token/exchange.

The access_token can then be used to call Plaid endpoints and obtain information about an Item.

In addition to the primary flow, several other token flows exist. The Link update mode flow allows you to update an access_token that has stopped working. The Sandbox testing environment also offers the /sandbox/public_token/create endpoint, which allows you to create a public_token without using Link.

Token endpoints

In this section
/link/token/createCreate a token for initializing a Link session
/link/token/getGet details about a previously created Link token
/item/public_token/exchangeExchange a public token from Link for an access token
/item/access_token/invalidateRotate an access token without deleting the Item
/item/public_token/create(Deprecated) Create a public token for legacy flows

/link/token/create

Create Link Token

The /link/token/create endpoint creates a link_token, which is required as a parameter when initializing Link. Once Link has been initialized, it returns a public_token, which can then be exchanged for an access_token via /item/public_token/exchange as part of the main Link flow.
A link_token generated by /link/token/create is also used to initialize other Link flows, such as the update mode flow for tokens with expired credentials, or the Payment Initiation (Europe) flow.

link/token/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_name
requiredstring
The name of your application, as it should be displayed in Link. Maximum length of 30 characters. If a value longer than 30 characters is provided, Link will display "This Application" instead.
language
requiredstring
The language that Link should be displayed in. When initializing with Identity Verification, this field is not used; for more details, see Identity Verification supported languages.
Supported languages are:
  • Danish ('da')
  • Dutch ('nl')
  • English ('en')
  • Estonian ('et')
  • French ('fr')
  • German ('de')
  • Italian ('it')
  • Latvian ('lv')
  • Lithuanian ('lt')
  • Norwegian ('no')
  • Polish ('pl')
  • Portuguese ('pt')
  • Romanian ('ro')
  • Spanish ('es')
  • Swedish ('sv')

When using a Link customization, the language configured here must match the setting in the customization, or the customization will not be applied.
country_codes
required[string]
Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard. Institutions from all listed countries will be shown. For a complete mapping of supported products by country, see https://plaid.com/global/.
If Link is launched with multiple country codes, only products that you are enabled for in all countries will be used by Link. Note that while all countries are enabled by default in Sandbox and Development, in Production only US and Canada are enabled by default. Access to European institutions requires additional compliance steps. To request access to European institutions in the Production environment, file a product access Support ticket via the Plaid dashboard. If you initialize with a European country code, your users will see the European consent panel during the Link flow.
If using a Link customization, make sure the country codes in the customization match those specified in country_codes, or the customization may not be applied.
If using the Auth features Instant Match, Same-day Micro-deposits, or Automated Micro-deposits, country_codes must be set to ['US'].

Min items: 1
Possible values: US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT
user
requiredobject
An object specifying information about the end user who will be linking their account.
client_user_id
requiredstring
A unique ID representing the end user. Typically this will be a user ID number from your application. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id. It is currently used as a means of searching logs for the given user in the Plaid Dashboard.
legal_name
string
The user's full legal name, used for micro-deposit based verification flows. For a small number of customers on legacy flows, providing this field is required to enable micro-deposit-based flows. For all other customers, this field is optional, but providing the user's name in this field when using micro-deposit-based verification will enable certain risk checks and can reduce micro-deposit fraud.
name
object
The user's full name. Optional if using the Identity Verification product; if not using Identity Verification, this field is not allowed. Users will not be asked for their name when this field is provided.
given_name
requiredstring
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
requiredstring
A string with at least one non-whitespace character, with a max length of 100 characters.
phone_number
string
The user's phone number in E.164 format. This field is optional, but required to enable the returning user experience. Can also be used to prefill Link fields when used with Identity Verification.
phone_number_verified_time
deprecatedstring
The date and time the phone number was verified in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ). This was previously an optional field used in the returning user experience. This field is no longer required to enable the returning user experience.
Only pass a verification time for a phone number that you have verified. If you have performed verification but don’t have the time, you may supply a signal value of the start of the UNIX epoch.
Example: 2020-01-01T00:00:00Z

Format: date-time
email_address
string
The user's email address. This field is optional, but required to enable the pre-authenticated returning user flow. Can also be used to prefill Link fields when used with Identity Verification.
email_address_verified_time
deprecatedstring
The date and time the email address was verified in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ). This was previously an optional field used in the returning user experience. This field is no longer required to enable the returning user experience.
Only pass a verification time for an email address that you have verified. If you have performed verification but don’t have the time, you may supply a signal value of the start of the UNIX epoch.
Example: 2020-01-01T00:00:00Z

Format: date-time
ssn
deprecatedstring
Deprecated and not currently used, use the id_number field instead.
date_of_birth
string
To be provided in the format "yyyy-mm-dd". Can be used to prefill Link fields when used with Identity Verification.

Format: date
address
object
The user's address. Used only for Identity Verification. If provided, the user will not be shown fields to enter their address in the Identity Verification flow. May be omitted, but if not omitted, all fields marked as required must be provided.
street
requiredstring
The primary street portion of an address. If the user has submitted their address, this field will always be filled.
street2
string
Extra street information, like an apartment or suite number.
city
requiredstring
City from the end user's address
region
string
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
string
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
requiredstring
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
id_number
object
The user's ID number. Used only for Identity Verification. If provided, the user will not be shown fields to enter their ID number in the Identity Verification flow. May be omitted, but if not omitted, all fields marked as required must be provided.
value
requiredstring
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
requiredstring
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
products
[string]
List of Plaid product(s) you wish to use. If launching Link in update mode, should be omitted (unless you are using update mode to add Income or Assets to an Item); required otherwise.
balance is not a valid value, the Balance product does not require explicit initialization and will automatically be initialized when any other product is initialized.
The products specified here will determine which institutions will be available to your users in Link. Only institutions that support all requested products can be selected; a if a user attempts to select an institution that does not support a listed product, a "Connectivity not supported" error message will appear in Link. To maximize the number of institutions available, initialize Link with the minimal product set required for your use case. Additional products can be included via the required_if_supported_products field, or can be initialized by calling the endpoint after obtaining an access token. For details and exceptions, see Choosing when to initialize products.
Note that, unless you have opted to disable Instant Match support, institutions that support Instant Match will also be shown in Link if auth is specified as a product, even though these institutions do not contain auth in their product array.
In Production, you will be billed for each product that you specify when initializing Link. Note that a product cannot be removed from an Item once the Item has been initialized with that product. To stop billing on an Item for subscription-based products, such as Liabilities, Investments, and Transactions, remove the Item via /item/remove.

Possible values: assets, auth, employment, identity, income_verification, identity_verification, investments, liabilities, payment_initiation, standing_orders, transactions, transfer, signal
additional_consented_products
[string]
(Beta) This field has no effect unless you are participating in the Data Transparency beta program. List of additional Plaid product(s) you wish to collect consent for. These products will not be billed until you start using them by calling the relevant endpoints.
balance is not a valid value, the Balance product does not require explicit initialization and will automatically have consent collected.
Institutions that do not support these products will still be shown in Link

Possible values: auth, identity, investments, liabilities, transactions, signal
required_if_supported_products
[string]
List of Plaid product(s) you wish to use only if the institution and account(s) selected by the user support the product. Institutions that do not support these products will still be shown in Link. The products will only be extracted and billed if the user selects an institution and account type that supports them.
There should be no overlap between products and required_if_supported_products. The products array must have at least one product.
For more details on using this feature, see Required if Supported Products.

Possible values: auth, identity, investments, liabilities, transactions, statements
webhook
string
The destination URL to which any webhooks should be sent. Note that webhooks for Payment Initiation (e-wallet transactions only), Transfer, Bank Transfer (including Auth micro-deposit notification webhooks) and Identity Verification are configured via the Dashboard instead.
access_token
string
The access_token associated with the Item to update or reference, used when updating, modifying, or accessing an existing access_token. Used when launching Link in update mode, when completing the Same-day (manual) Micro-deposit flow, or (optionally) when initializing Link for a returning user as part of the Transfer UI flow.
link_customization_name
string
The name of the Link customization from the Plaid Dashboard to be applied to Link. If not specified, the default customization will be used. When using a Link customization, the language in the customization must match the language selected via the language parameter, and the countries in the customization should match the country codes selected via country_codes.
redirect_uri
string
A URI indicating the destination where a user should be forwarded after completing the Link flow; used to support OAuth authentication flows when launching Link in the browser or via a webview. The redirect_uri should not contain any query parameters. When used in Production or Development, must be an https URI. To specify any subdomain, use * as a wildcard character, e.g. https://*.example.com/oauth.html. Note that any redirect URI must also be added to the Allowed redirect URIs list in the developer dashboard. If initializing on Android, android_package_name must be specified instead and redirect_uri should be left blank.
android_package_name
string
The name of your app's Android package. Required if using the link_token to initialize Link on Android. Any package name specified here must also be added to the Allowed Android package names setting on the developer dashboard. When creating a link_token for initializing Link on other platforms, android_package_name must be left blank and redirect_uri should be used instead.
institution_data
object
A map containing data used to highlight institutions in Link.
routing_number
string
The routing number of the bank to highlight.
account_filters
object
By default, Link will provide limited account filtering: it will only display Institutions that are compatible with all products supplied in the products parameter of /link/token/create, and, if auth is specified in the products array, will also filter out accounts other than checking and savings accounts on the Account Select pane. You can further limit the accounts shown in Link by using account_filters to specify the account subtypes to be shown in Link. Only the specified subtypes will be shown. This filtering applies to both the Account Select view (if enabled) and the Institution Select view. Institutions that do not support the selected subtypes will be omitted from Link. To indicate that all subtypes should be shown, use the value "all". If the account_filters filter is used, any account type for which a filter is not specified will be entirely omitted from Link. For a full list of valid types and subtypes, see the Account schema.
For institutions using OAuth, the filter will not affect the list of accounts shown by the bank in the OAuth window.
depository
object
A filter to apply to depository-type accounts
account_subtypes
required[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: checking, savings, hsa, cd, money market, paypal, prepaid, cash management, ebt, all
credit
object
A filter to apply to credit-type accounts
account_subtypes
required[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: credit card, paypal, all
loan
object
A filter to apply to loan-type accounts
account_subtypes
required[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: auto, business, commercial, construction, consumer, home equity, loan, mortgage, line of credit, student, other, all
investment
object
A filter to apply to investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier).
account_subtypes
required[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: 529, 401a, 401k, 403B, 457b, brokerage, cash isa, crypto exchange, education savings account, fixed annuity, gic, health reimbursement arrangement, hsa, ira, isa, keogh, lif, life insurance, lira, lrif, lrsp, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other annuity, other insurance, pension, prif, profit sharing plan, qshr, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, sep ira, simple ira, sipp, stock plan, tfsa, trust, ugma, utma, variable annuity, all
eu_config
object
Configuration parameters for EU flows
headless
boolean
If true, open Link without an initial UI. Defaults to false.
institution_id
string
Used for certain Europe-only configurations, as well as certain legacy use cases in other regions.
payment_initiation
object
Specifies options for initializing Link for use with the Payment Initiation (Europe) product. This field is required if payment_initiation is included in the products array. Either payment_id or consent_id must be provided.
payment_id
string
The payment_id provided by the /payment_initiation/payment/create endpoint.
consent_id
string
The consent_id provided by the /payment_initiation/consent/create endpoint.
income_verification
object
Specifies options for initializing Link for use with the Income product. This field is required if income_verification is included in the products array.
income_verification_id
deprecatedstring
The income_verification_id of the verification instance, as provided by /income/verification/create.
asset_report_id
string
The asset_report_id of an asset report associated with the user, as provided by /asset_report/create. Providing an asset_report_id is optional and can be used to verify the user through a streamlined flow. If provided, the bank linking flow will be skipped.
precheck_id
string
The ID of a precheck created with /income/verification/precheck. Will be used to improve conversion of the income verification flow by streamlining the Link interface presented to the end user.
access_tokens
[string]
An array of access tokens corresponding to Items that a user has previously connected with. Data from these institutions will be cross-referenced with document data received during the Document Income flow to help verify that the uploaded documents are accurate. If the transactions product was not initialized for these Items during link, it will be initialized after this Link session.
This field should only be used with the payroll income source type.
income_source_types
[string]
The types of source income data that users will be permitted to share. Options include bank and payroll. Currently you can only specify one of these options.

Possible values: bank, payroll
bank_income
object
Specifies options for initializing Link for use with Bank Income. This field is required if income_verification is included in the products array and bank is specified in income_source_types.
days_requested
requiredinteger
The number of days of data to request for the Bank Income product

Minimum: 1
Maximum: 731
enable_multiple_items
boolean
Whether to enable multiple Items to be added in the Link session

Default: false
payroll_income
object
Specifies options for initializing Link for use with Payroll Income (including Document Income). Further customization options for Document Income, such as customizing which document types may be uploaded, are also available via the Link Customization pane in the Dashboard. (Requires Production enablement.)
flow_types
[string]
The types of payroll income verification to enable for the Link session. If none are specified, then users will see both document and digital payroll income.

Possible values: payroll_digital_income, payroll_document_income
is_update_mode
boolean
An identifier to indicate whether the income verification Link token will be used for update mode. This field is only relevant for participants in the Payroll Income Refresh beta.

Default: false
item_id_to_update
string
Uniquely identify a payroll income Item to update with. This field is only relevant for participants in the Payroll Income Refresh beta.
parsing_config
[string]
The types of analysis to enable for document uploads. If none are specified, then docs will undergo OCR parsing only. This field is only relevant to participants in the Document Fraud beta.

Possible values: ocr, fraud_risk
stated_income_sources
[object]
A list of user stated income sources
employer
string
The employer corresponding to an income source specified by the user
category
string
The income category for a specified income source

Possible values: OTHER, SALARY, UNEMPLOYMENT, CASH, GIG_ECONOMY, RENTAL, CHILD_SUPPORT, MILITARY, RETIREMENT, LONG_TERM_DISABILITY, BANK_INTEREST
pay_per_cycle
number
The income amount paid per cycle for a specified income source

Format: double
pay_annual
number
The income amount paid annually for a specified income source

Format: double
pay_type
string
The pay type - GROSS, NET, or UNKNOWN for a specified income source

Possible values: UNKNOWN, GROSS, NET
pay_frequency
string
The pay frequency of a specified income source

Possible values: UNKNOWN, WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY
auth
object
Specifies options for initializing Link for use with the Auth product. This field can be used to enable or disable extended Auth flows for the resulting Link session. Omitting any field will result in a default that can be configured by your account manager.
auth_type_select_enabled
boolean
Specifies whether Auth Type Select is enabled for the Link session, allowing the end user to choose between linking instantly or manually prior to selecting their financial institution. Note that this can only be true if same_day_microdeposits_enabled is set to true.

Default: false
automated_microdeposits_enabled
boolean
Specifies whether the Link session is enabled for the Automated Micro-deposits flow.
instant_match_enabled
boolean
Specifies whether the Link session is enabled for the Instant Match flow. As of November 2022, Instant Match will be enabled by default. Instant Match can be disabled by setting this field to false.
same_day_microdeposits_enabled
boolean
Specifies whether the Link session is enabled for the Same Day Micro-deposits flow.
reroute_to_credentials
string
Specifies what type of Reroute to Credentials pane should be used in the Link session for the Same Day Micro-deposits flow.

Possible values: OFF, OPTIONAL, FORCED
flow_type
deprecatedstring
This field has been deprecated in favor of auth_type_select_enabled.

Possible values: FLEXIBLE_AUTH
transfer
object
Specifies options for initializing Link for use with the Transfer product.
intent_id
string
The id returned by the /transfer/intent/create endpoint.
payment_profile_token
string
The payment_profile_token returned by the /payment_profile/create endpoint.
update
object
Specifies options for initializing Link for update mode.
account_selection_enabled
boolean
If true, enables update mode with Account Select for institutions that do not use OAuth, or that use OAuth but do not have their own account selection flow. For institutions that have an OAuth account selection flow (i.e. most OAuth-enabled institutions), update mode with Account Select will always be enabled, regardless of the value of this field.

Default: false
identity_verification
object
Specifies option for initializing Link for use with the Identity Verification product.
template_id
requiredstring
ID of the associated Identity Verification template.
gave_consent
boolean
A flag specifying whether the end user has already agreed to a privacy policy specifying that their data will be shared with Plaid for verification purposes.
If gave_consent is set to true, the accept_tos step will be marked as skipped and the end user's session will start at the next step requirement.

Default: false
user_token
string
A user token generated using /user/create. Any Item created during the Link session will be associated with the user.
investments
object
Configuration parameters for the Investments product
allow_unverified_crypto_wallets
boolean
If true, allow self-custody crypto wallets to be added without requiring signature verification. Defaults to false.
Select group for content switcher
Select Language
1const request: LinkTokenCreateRequest = {
2  user: {
3    client_user_id: 'user-id',
4  },
5  client_name: 'Plaid Test App',
6  products: ['auth', 'transactions'],
7  country_codes: ['US'],
8  language: 'en',
9  webhook: 'https://sample-web-hook.com',
10  redirect_uri: 'https://domainname.com/oauth-page.html',
11  account_filters: {
12    depository: {
13      account_subtypes: ["checking", "savings"],
14    },
15  },
16};
17try {
18  const response = await plaidClient.linkTokenCreate(request);
19  const linkToken = response.data.link_token;
20} catch (error) {
21  // handle error
22}
link/token/create

Response fields and example

link_token
string
A link_token, which can be supplied to Link in order to initialize it and receive a public_token, which can be exchanged for an access_token.
expiration
string
The expiration date for the link_token, in ISO 8601 format. A link_token created to generate a public_token that will be exchanged for a new access_token expires after 4 hours. A link_token created for an existing Item (such as when updating an existing access_token by launching Link in update mode) expires after 30 minutes.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176",
3  "expiration": "2020-03-27T12:56:34Z",
4  "request_id": "XQVgFigpGHXkb0b"
5}
Was this helpful?

/link/token/get

Get Link Token

The /link/token/get endpoint gets information about a previously-created link_token using the /link/token/create endpoint. It can be useful for debugging purposes.

link/token/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
link_token
requiredstring
A link_token from a previous invocation of /link/token/create
Select group for content switcher
Select Language
1const request: LinkTokenGetRequest = {
2  link_token: linkToken,
3};
4try {
5  const response = await plaidClient.linkTokenGet(request);
6} catch (error) {
7  // handle error
8}
link/token/get

Response fields and example

link_token
string
A link_token, which can be supplied to Link in order to initialize it and receive a public_token, which can be exchanged for an access_token.
created_at
nullablestring
The creation timestamp for the link_token, in ISO 8601 format.

Format: date-time
expiration
nullablestring
The expiration timestamp for the link_token, in ISO 8601 format.

Format: date-time
metadata
object
An object specifying the arguments originally provided to the /link/token/create call.
initial_products
[string]
The products specified in the /link/token/create call.

Possible values: assets, auth, employment, identity, income_verification, identity_verification, investments, liabilities, payment_initiation, standing_orders, transactions, transfer
webhook
nullablestring
The webhook specified in the /link/token/create call.
country_codes
[string]
The country_codes specified in the /link/token/create call.

Possible values: US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT
language
nullablestring
The language specified in the /link/token/create call.
institution_data
object
A map containing data used to highlight institutions in Link.
routing_number
string
The routing number of the bank to highlight.
account_filters
object
The account_filters specified in the original call to /link/token/create.
depository
object
A filter to apply to depository-type accounts
account_subtypes
[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: checking, savings, hsa, cd, money market, paypal, prepaid, cash management, ebt, all
credit
object
A filter to apply to credit-type accounts
account_subtypes
[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: credit card, paypal, all
loan
object
A filter to apply to loan-type accounts
account_subtypes
[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: auto, business, commercial, construction, consumer, home equity, loan, mortgage, line of credit, student, other, all
investment
object
A filter to apply to investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier).
account_subtypes
[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: 529, 401a, 401k, 403B, 457b, brokerage, cash isa, crypto exchange, education savings account, fixed annuity, gic, health reimbursement arrangement, hsa, ira, isa, keogh, lif, life insurance, lira, lrif, lrsp, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other annuity, other insurance, pension, prif, profit sharing plan, qshr, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, sep ira, simple ira, sipp, stock plan, tfsa, trust, ugma, utma, variable annuity, all
redirect_uri
nullablestring
The redirect_uri specified in the /link/token/create call.
client_name
nullablestring
The client_name specified in the /link/token/create call.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "created_at": "2020-12-02T21:14:54Z",
3  "expiration": "2020-12-03T01:14:54Z",
4  "link_token": "link-sandbox-33792986-2b9c-4b80-b1f2-518caaac6183",
5  "metadata": {
6    "account_filters": {
7      "depository": {
8        "account_subtypes": [
9          "checking",
10          "savings"
11        ]
12      }
13    },
14    "client_name": "Insert Client name here",
15    "country_codes": [
16      "US"
17    ],
18    "initial_products": [
19      "auth"
20    ],
21    "language": "en",
22    "redirect_uri": null,
23    "webhook": "https://www.example.com/webhook"
24  },
25  "request_id": "u0ydFs493XjyTYn"
26}
Was this helpful?

/item/public_token/exchange

Exchange public token for an access token

Exchange a Link public_token for an API access_token. Link hands off the public_token client-side via the onSuccess callback once a user has successfully created an Item. The public_token is ephemeral and expires after 30 minutes. An access_token does not expire, but can be revoked by calling /item/remove.
The response also includes an item_id that should be stored with the access_token. The item_id is used to identify an Item in a webhook. The item_id can also be retrieved by making an /item/get request.

item/public_token/exchange

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
public_token
requiredstring
Your public_token, obtained from the Link onSuccess callback or /sandbox/item/public_token/create.
Select group for content switcher
Select Language
1const request: ItemPublicTokenExchangeRequest = {
2  public_token: publicToken,
3};
4try {
5  const response = await plaidClient.itemPublicTokenExchange(request);
6  const accessToken = response.data.access_token;
7  const itemId = response.data.item_id;
8} catch (err) {
9  // handle error
10}
item/public_token/exchange

Response fields and example

access_token
string
The access token associated with the Item data is being requested for.
item_id
string
The item_id value of the Item associated with the returned access_token
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
3  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
4  "request_id": "Aim3b"
5}
Was this helpful?

/item/access_token/invalidate

Invalidate access_token

By default, the access_token associated with an Item does not expire and should be stored in a persistent, secure manner.
You can use the /item/access_token/invalidate endpoint to rotate the access_token associated with an Item. The endpoint returns a new access_token and immediately invalidates the previous access_token.

item/access_token/invalidate

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
Select group for content switcher
Select Language
1// Generate a new access_token for an Item, invalidating the old one
2const request: ItemAccessTokenInvalidateRequest = {
3  access_token: accessToken,
4};
5try {
6  const response = await plaidClient.itemAccessTokenInvalidate(request);
7  // Store the new access_token in a persistent, secure datastore
8  const accessToken = response.data.new_access_token;
9} catch (error) {
10  // handle error
11}
item/access_token/invalidate

Response fields and example

new_access_token
string
The access token associated with the Item data is being requested for.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "new_access_token": "access-sandbox-8ab976e6-64bc-4b38-98f7-731e7a349970",
3  "request_id": "m8MDnv9okwxFNBV"
4}
Was this helpful?

/item/public_token/create

Create public token

Note: As of July 2020, the /item/public_token/create endpoint is deprecated. Instead, use /link/token/create with an access_token to create a Link token for use with update mode.
If you need your user to take action to restore or resolve an error associated with an Item, generate a public token with the /item/public_token/create endpoint and then initialize Link with that public_token.
A public_token is one-time use and expires after 30 minutes. You use a public_token to initialize Link in update mode for a particular Item. You can generate a public_token for an Item even if you did not use Link to create the Item originally.
The /item/public_token/create endpoint is not used to create your initial public_token. If you have not already received an access_token for a specific Item, use Link to obtain your public_token instead. See the Quickstart for more information.

item/public_token/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
Select group for content switcher
Select Language
1// This endpoint is deprecated and not
2// supported in the Beta libraries
item/public_token/create

Response fields and example

public_token
string
A public_token for the particular Item corresponding to the specified access_token
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
3  "request_id": "Aim3b"
4}
Was this helpful?

link android troubleshooting

Troubleshooting the Plaid Link Android SDK

Enabling Logs

The Link SDK logs information to LogCat at several points in the flow. Pass a LinkLogLevel value with the LinkTokenConfiguration to see the logs. The levels from least to most verbose: ERROR, WARN, INFO, DEBUG, VERBOSE.

Select Language
1val linkTokenConfiguration = linkTokenConfiguration {
2  token = "LINK_TOKEN_FROM_SERVER"
3  logLevel = if (BuildConfig.DEBUG) LinkLogLevel.VERBOSE else LinkLogLevel.ERROR
4}

Troubleshooting OAuth errors

A troubleshooting guide for common OAuth errors is below.

No redirect out of app

Link user experience
  • In Link, after clicking "Continue" on the OAuth screen, nothing happens.
Common causes
  • The user may be using an unsupported browser that is not compatible with Plaid's OAuth redirects, such as DuckDuckGo. For more details on which browsers are supported, see Supported browsers.
Troubleshooting steps

No redirect back to app

Link user experience
  • After completing OAuth in the browser or financial institution's app, the user is not redirected back to your app.
Common causes
  • The webpage is unable to locate an app on the device with a package id matching the one used to create the Link token.
Troubleshooting steps

The Play Store opened upon redirect

Link user experience
  • After completing OAuth in the browser or financial institution's app, the Google Play store opened.
Common causes
  • The webpage is unable to locate an app on the device with the package id matching the one used to create the Link token.
Troubleshooting steps

Link opens, then immediately closes upon redirect

Link user experience

After completing OAuth in the browser or financial institution's app, Link opens and then closes again.

Common causes
  • The webpage redirected back to the wrong application on the device causing Link to open and immediately close again as it gets data from a different session.
  • You may have both a test and a release version of your app installed on your device and used the wrong package name when creating the Link token.
Troubleshooting steps

Other common errors

To troubleshoot an error with an error code, use the error troubleshooting guide.

api products liabilities

Liabilities

API reference for Liabilities endpoints and webhooks

Endpoints
/liabilities/getFetch liabilities data
Webhooks
DEFAULT_UPDATENew or updated liabilities available

Endpoints

/liabilities/get

Retrieve Liabilities data

The /liabilities/get endpoint returns various details about an Item with loan or credit accounts. Liabilities data is available primarily for US financial institutions, with some limited coverage of Canadian institutions. Currently supported account types are account type credit with account subtype credit card or paypal, and account type loan with account subtype student or mortgage. To limit accounts listed in Link to types and subtypes supported by Liabilities, you can use the account_filters parameter when creating a Link token.
The types of information returned by Liabilities can include balances and due dates, loan terms, and account details such as original loan amount and guarantor. Data is refreshed approximately once per day; the latest data can be retrieved by calling /liabilities/get.
Note: This request may take some time to complete if liabilities was not specified as an initial product when creating the Item. This is because Plaid must communicate directly with the institution to retrieve the additional data.

liabilities/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
options
object
An optional object to filter /liabilities/get results. If provided, options cannot be null.
account_ids
[string]
A list of accounts to retrieve for the Item.
An error will be returned if a provided account_id is not associated with the Item
Select group for content switcher
Select Language
1// Retrieve Liabilities data for an Item
2const request: LiabilitiesGetRequest = {
3  access_token: accessToken,
4};
5try {
6  const response = await plaidClient.liabilitiesGet(request);
7  const liabilities = response.data.liabilities;
8} catch (error) {
9  // handle error
10}
liabilities/get

Response fields and example

accounts
[object]
An array of accounts associated with the Item
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullablenumber
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullablenumber
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullablenumber
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullablestring
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
item
object
Metadata about the Item.
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
nullablestring
The Plaid Institution ID associated with the Item. Field is null for Items created via Same Day Micro-deposits.
webhook
nullablestring
The URL registered to receive webhooks for the Item.
error
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
available_products
[string]
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
billed_products
[string]
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available_products. Note - billed_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
products
[string]
A list of initialized products for the Item. In almost all cases, this will be the same as the billed_products field. For some products, it is possible for the product to be initialized on an Item but not yet billed (e.g. Assets, before /asset_report/create has been called), in which case the product may appear in products but not in billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consented_products
[string]
A list of products that have gone through consent collection for the Item. Only present for those enabled in the Data Transparency beta. If you are not enrolled in Data Transparency, this field is not used.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consent_expiration_time
nullablestring
The RFC 3339 timestamp after which the consent provided by the end user will expire. Upon consent expiration, the item will enter the ITEM_LOGIN_REQUIRED error state. To circumvent the ITEM_LOGIN_REQUIRED error and maintain continuous consent, the end user can reauthenticate via Link’s update mode in advance of the consent expiration time.
Note - This is only relevant for certain OAuth-based institutions. For all other institutions, this field will be null.

Format: date-time
update_type
string
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication.
background - Item can be updated in the background
user_present_required - Item requires user interaction to be updated

Possible values: background, user_present_required
liabilities
object
An object containing liability accounts
credit
nullable[object]
The credit accounts returned.
account_id
nullablestring
The ID of the account that this liability belongs to.
aprs
[object]
The various interest rates that apply to the account. APR information is not provided by all card issuers; if APR data is not available, this array will be empty.
apr_percentage
number
Annual Percentage Rate applied.

Format: double
apr_type
string
The type of balance to which the APR applies.

Possible values: balance_transfer_apr, cash_apr, purchase_apr, special
balance_subject_to_apr
nullablenumber
Amount of money that is subjected to the APR if a balance was carried beyond payment due date. How it is calculated can vary by card issuer. It is often calculated as an average daily balance.

Format: double
interest_charge_amount
nullablenumber
Amount of money charged due to interest from last statement.

Format: double
is_overdue
nullableboolean
true if a payment is currently overdue. Availability for this field is limited.
last_payment_amount
nullablenumber
The amount of the last payment.

Format: double
last_payment_date
nullablestring
The date of the last payment. Dates are returned in an ISO 8601 format (YYYY-MM-DD). Availability for this field is limited.

Format: date
last_statement_issue_date
nullablestring
The date of the last statement. Dates are returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
last_statement_balance
nullablenumber
The total amount owed as of the last statement issued

Format: double
minimum_payment_amount
nullablenumber
The minimum payment due for the next billing cycle.

Format: double
next_payment_due_date
nullablestring
The due date for the next payment. The due date is null if a payment is not expected. Dates are returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
mortgage
nullable[object]
The mortgage accounts returned.
account_id
string
The ID of the account that this liability belongs to.
account_number
string
The account number of the loan.
current_late_fee
nullablenumber
The current outstanding amount charged for late payment.

Format: double
escrow_balance
nullablenumber
Total amount held in escrow to pay taxes and insurance on behalf of the borrower.

Format: double
has_pmi
nullableboolean
Indicates whether the borrower has private mortgage insurance in effect.
has_prepayment_penalty
nullableboolean
Indicates whether the borrower will pay a penalty for early payoff of mortgage.
interest_rate
object
Object containing metadata about the interest rate for the mortgage.
percentage
nullablenumber
Percentage value (interest rate of current mortgage, not APR) of interest payable on a loan.

Format: double
type
nullablestring
The type of interest charged (fixed or variable).
last_payment_amount
nullablenumber
The amount of the last payment.

Format: double
last_payment_date
nullablestring
The date of the last payment. Dates are returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
loan_type_description
nullablestring
Description of the type of loan, for example conventional, fixed, or variable. This field is provided directly from the loan servicer and does not have an enumerated set of possible values.
loan_term
nullablestring
Full duration of mortgage as at origination (e.g. 10 year).
maturity_date
nullablestring
Original date on which mortgage is due in full. Dates are returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
next_monthly_payment
nullablenumber
The amount of the next payment.

Format: double
next_payment_due_date
nullablestring
The due date for the next payment. Dates are returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
origination_date
nullablestring
The date on which the loan was initially lent. Dates are returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
origination_principal_amount
nullablenumber
The original principal balance of the mortgage.

Format: double
past_due_amount
nullablenumber
Amount of loan (principal + interest) past due for payment.

Format: double
property_address
object
Object containing fields describing property address.
city
nullablestring
The city name.
country
nullablestring
The ISO 3166-1 alpha-2 country code.
postal_code
nullablestring
The five or nine digit postal code.
region
nullablestring
The region or state (example "NC").
street
nullablestring
The full street address (example "564 Main Street, Apt 15").
ytd_interest_paid
nullablenumber
The year to date (YTD) interest paid.

Format: double
ytd_principal_paid
nullablenumber
The YTD principal paid.

Format: double
student
nullable[object]
The student loan accounts returned.
account_id
nullablestring
The ID of the account that this liability belongs to.
account_number
nullablestring
The account number of the loan. For some institutions, this may be a masked version of the number (e.g., the last 4 digits instead of the entire number).
disbursement_dates
nullable[string]
The dates on which loaned funds were disbursed or will be disbursed. These are often in the past. Dates are returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
expected_payoff_date
nullablestring
The date when the student loan is expected to be paid off. Availability for this field is limited. Dates are returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
guarantor
nullablestring
The guarantor of the student loan.
interest_rate_percentage
number
The interest rate on the loan as a percentage.

Format: double
is_overdue
nullableboolean
true if a payment is currently overdue. Availability for this field is limited.
last_payment_amount
nullablenumber
The amount of the last payment.

Format: double
last_payment_date
nullablestring
The date of the last payment. Dates are returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
last_statement_issue_date
nullablestring
The date of the last statement. Dates are returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
loan_name
nullablestring
The type of loan, e.g., "Consolidation Loans".
loan_status
object
An object representing the status of the student loan
end_date
nullablestring
The date until which the loan will be in its current status. Dates are returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
type
nullablestring
The status type of the student loan

Possible values: cancelled, charged off, claim, consolidated, deferment, delinquent, discharged, extension, forbearance, in grace, in military, in school, not fully disbursed, other, paid in full, refunded, repayment, transferred
minimum_payment_amount
nullablenumber
The minimum payment due for the next billing cycle. There are some exceptions: Some institutions require a minimum payment across all loans associated with an account number. Our API presents that same minimum payment amount on each loan. The institutions that do this are: Great Lakes ( ins_116861), Firstmark (ins_116295), Commonbond Firstmark Services (ins_116950), Nelnet (ins_116528), EdFinancial Services (ins_116304), Granite State (ins_116308), and Oklahoma Student Loan Authority (ins_116945). Firstmark (ins_116295 ) and Navient (ins_116248) will display as $0 if there is an autopay program in effect.

Format: double
next_payment_due_date
nullablestring
The due date for the next payment. The due date is null if a payment is not expected. A payment is not expected if loan_status.type is deferment, in_school, consolidated, paid in full, or transferred. Dates are returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
origination_date
nullablestring
The date on which the loan was initially lent. Dates are returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
origination_principal_amount
nullablenumber
The original principal balance of the loan.

Format: double
outstanding_interest_amount
nullablenumber
The total dollar amount of the accrued interest balance. For Sallie Mae ( ins_116944), this amount is included in the current balance of the loan, so this field will return as null.

Format: double
payment_reference_number
nullablestring
The relevant account number that should be used to reference this loan for payments. In the majority of cases, payment_reference_number will match account_number, but in some institutions, such as Great Lakes (ins_116861), it will be different.
pslf_status
object
Information about the student's eligibility in the Public Service Loan Forgiveness program. This is only returned if the institution is FedLoan (ins_116527).
estimated_eligibility_date
nullablestring
The estimated date borrower will have completed 120 qualifying monthly payments. Returned in ISO 8601 format (YYYY-MM-DD).

Format: date
payments_made
nullableinteger
The number of qualifying payments that have been made.
payments_remaining
nullableinteger
The number of qualifying payments remaining.
repayment_plan
object
An object representing the repayment plan for the student loan
description
nullablestring
The description of the repayment plan as provided by the servicer.
type
nullablestring
The type of the repayment plan.

Possible values: extended graduated, extended standard, graduated, income-contingent repayment, income-based repayment, interest-only, other, pay as you earn, revised pay as you earn, standard, null
sequence_number
nullablestring
The sequence number of the student loan. Heartland ECSI (ins_116948) does not make this field available.
servicer_address
object
The address of the student loan servicer. This is generally the remittance address to which payments should be sent.
city
nullablestring
The full city name
region
nullablestring
The region or state Example: "NC"
street
nullablestring
The full street address Example: "564 Main Street, APT 15"
postal_code
nullablestring
The postal code
country
nullablestring
The ISO 3166-1 alpha-2 country code
ytd_interest_paid
nullablenumber
The year to date (YTD) interest paid. Availability for this field is limited.

Format: double
ytd_principal_paid
nullablenumber
The year to date (YTD) principal paid. Availability for this field is limited.

Format: double
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "accounts": [
3    {
4      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
5      "balances": {
6        "available": 100,
7        "current": 110,
8        "iso_currency_code": "USD",
9        "limit": null,
10        "unofficial_currency_code": null
11      },
12      "mask": "0000",
13      "name": "Plaid Checking",
14      "official_name": "Plaid Gold Standard 0% Interest Checking",
15      "subtype": "checking",
16      "type": "depository"
17    },
18    {
19      "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
20      "balances": {
21        "available": null,
22        "current": 410,
23        "iso_currency_code": "USD",
24        "limit": 2000,
25        "unofficial_currency_code": null
26      },
27      "mask": "3333",
28      "name": "Plaid Credit Card",
29      "official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
30      "subtype": "credit card",
31      "type": "credit"
32    },
33    {
34      "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
35      "balances": {
36        "available": null,
37        "current": 65262,
38        "iso_currency_code": "USD",
39        "limit": null,
40        "unofficial_currency_code": null
41      },
42      "mask": "7777",
43      "name": "Plaid Student Loan",
44      "official_name": null,
45      "subtype": "student",
46      "type": "loan"
47    },
48    {
49      "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
50      "balances": {
51        "available": null,
52        "current": 56302.06,
53        "iso_currency_code": "USD",
54        "limit": null,
55        "unofficial_currency_code": null
56      },
57      "mask": "8888",
58      "name": "Plaid Mortgage",
59      "official_name": null,
60      "subtype": "mortgage",
61      "type": "loan"
62    }
63  ],
64  "item": {
65    "available_products": [
66      "balance",
67      "investments"
68    ],
69    "billed_products": [
70      "assets",
71      "auth",
72      "identity",
73      "liabilities",
74      "transactions"
75    ],
76    "consent_expiration_time": null,
77    "error": null,
78    "institution_id": "ins_3",
79    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
80    "update_type": "background",
81    "webhook": "https://www.genericwebhookurl.com/webhook"
82  },
83  "liabilities": {
84    "credit": [
85      {
86        "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
87        "aprs": [
88          {
89            "apr_percentage": 15.24,
90            "apr_type": "balance_transfer_apr",
91            "balance_subject_to_apr": 1562.32,
92            "interest_charge_amount": 130.22
93          },
94          {
95            "apr_percentage": 27.95,
96            "apr_type": "cash_apr",
97            "balance_subject_to_apr": 56.22,
98            "interest_charge_amount": 14.81
99          },
100          {
101            "apr_percentage": 12.5,
102            "apr_type": "purchase_apr",
103            "balance_subject_to_apr": 157.01,
104            "interest_charge_amount": 25.66
105          },
106          {
107            "apr_percentage": 0,
108            "apr_type": "special",
109            "balance_subject_to_apr": 1000,
110            "interest_charge_amount": 0
111          }
112        ],
113        "is_overdue": false,
114        "last_payment_amount": 168.25,
115        "last_payment_date": "2019-05-22",
116        "last_statement_issue_date": "2019-05-28",
117        "last_statement_balance": 1708.77,
118        "minimum_payment_amount": 20,
119        "next_payment_due_date": "2020-05-28"
120      }
121    ],
122    "mortgage": [
123      {
124        "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
125        "account_number": "3120194154",
126        "current_late_fee": 25,
127        "escrow_balance": 3141.54,
128        "has_pmi": true,
129        "has_prepayment_penalty": true,
130        "interest_rate": {
131          "percentage": 3.99,
132          "type": "fixed"
133        },
134        "last_payment_amount": 3141.54,
135        "last_payment_date": "2019-08-01",
136        "loan_term": "30 year",
137        "loan_type_description": "conventional",
138        "maturity_date": "2045-07-31",
139        "next_monthly_payment": 3141.54,
140        "next_payment_due_date": "2019-11-15",
141        "origination_date": "2015-08-01",
142        "origination_principal_amount": 425000,
143        "past_due_amount": 2304,
144        "property_address": {
145          "city": "Malakoff",
146          "country": "US",
147          "postal_code": "14236",
148          "region": "NY",
149          "street": "2992 Cameron Road"
150        },
151        "ytd_interest_paid": 12300.4,
152        "ytd_principal_paid": 12340.5
153      }
154    ],
155    "student": [
156      {
157        "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
158        "account_number": "4277075694",
159        "disbursement_dates": [
160          "2002-08-28"
161        ],
162        "expected_payoff_date": "2032-07-28",
163        "guarantor": "DEPT OF ED",
164        "interest_rate_percentage": 5.25,
165        "is_overdue": false,
166        "last_payment_amount": 138.05,
167        "last_payment_date": "2019-04-22",
168        "last_statement_issue_date": "2019-04-28",
169        "loan_name": "Consolidation",
170        "loan_status": {
171          "end_date": "2032-07-28",
172          "type": "repayment"
173        },
174        "minimum_payment_amount": 25,
175        "next_payment_due_date": "2019-05-28",
176        "origination_date": "2002-08-28",
177        "origination_principal_amount": 25000,
178        "outstanding_interest_amount": 6227.36,
179        "payment_reference_number": "4277075694",
180        "pslf_status": {
181          "estimated_eligibility_date": "2021-01-01",
182          "payments_made": 200,
183          "payments_remaining": 160
184        },
185        "repayment_plan": {
186          "description": "Standard Repayment",
187          "type": "standard"
188        },
189        "sequence_number": "1",
190        "servicer_address": {
191          "city": "San Matias",
192          "country": "US",
193          "postal_code": "99415",
194          "region": "CA",
195          "street": "123 Relaxation Road"
196        },
197        "ytd_interest_paid": 280.55,
198        "ytd_principal_paid": 271.65
199      }
200    ]
201  },
202  "request_id": "dTnnm60WgKGLnKL"
203}
Was this helpful?

Webhooks

Liabilities webhooks are sent to indicate that new loans or updated loan fields for existing accounts are available.

DEFAULT_UPDATE

The webhook of type LIABILITIES and code DEFAULT_UPDATE will be fired when new or updated liabilities have been detected on a liabilities item.

webhook_type
string
LIABILITIES
webhook_code
string
DEFAULT_UPDATE
item_id
string
The item_id of the Item associated with this webhook, warning, or error
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
account_ids_with_new_liabilities
[string]
An array of account_id's for accounts that contain new liabilities.'
account_ids_with_updated_liabilities
object
An object with keys of account_id's that are mapped to their respective liabilities fields that changed.
Example: { "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58": ["past_amount_due"] }
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "LIABILITIES",
3  "webhook_code": "DEFAULT_UPDATE",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "error": null,
6  "account_ids_with_new_liabilities": [
7    "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58",
8    "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp"
9  ],
10  "account_ids_with_updated_liabilities": {
11    "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58": [
12      "past_amount_due"
13    ]
14  },
15  "environment": "production"
16}
Was this helpful?

api products identity

Identity

API reference for Identity endpoints and webhooks

Verify the name, address, phone number, and email address of a user against bank account information on file.

Endpoints
/identity/getFetch identity data
/identity/matchMatch client identity with bank identity

Endpoints

/identity/get

Retrieve identity data

The /identity/get endpoint allows you to retrieve various account holder information on file with the financial institution, including names, emails, phone numbers, and addresses. Only name data is guaranteed to be returned; other fields will be empty arrays if not provided by the institution.
This request may take some time to complete if identity was not specified as an initial product when creating the Item. This is because Plaid must communicate directly with the institution to retrieve the data.
Note: In API versions 2018-05-22 and earlier, the owners object is not returned, and instead identity information is returned in the top level identity object. For more details, see Plaid API versioning.

identity/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
options
object
An optional object to filter /identity/get results.
account_ids
[string]
A list of account_ids to retrieve for the Item. Note: An error will be returned if a provided account_id is not associated with the Item.
Select group for content switcher
Select Language
1// Pull Identity data for an Item
2const request: IdentityGetRequest = {
3  access_token: accessToken,
4};
5try {
6  const response = await plaidClient.identityGet(request);
7  const identities = response.data.accounts.flatMap(
8    (account) => account.owners,
9  );
10} catch (error) {
11  // handle error
12}
identity/get

Response fields and example

accounts
[object]
The accounts for which Identity data has been requested
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullablenumber
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullablenumber
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullablenumber
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullablestring
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
owners
[object]
Data returned by the financial institution about the account owner or owners. Only returned by Identity or Assets endpoints. For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution. Multiple owners on a single account will be represented in the same owner object, not in multiple owner objects within the array. In API versions 2018-05-22 and earlier, the owners object is not returned, and instead identity information is returned in the top level identity object. For more details, see Plaid API versioning
names
[string]
A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders.
If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.
phone_numbers
[object]
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
string
The phone number.
primary
boolean
When true, identifies the phone number as the primary number on an account.
type
string
The type of phone number.

Possible values: home, work, office, mobile, mobile1, other
emails
[object]
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
string
The email address.
primary
boolean
When true, identifies the email address as the primary email on an account.
type
string
The type of email account as described by the financial institution.

Possible values: primary, secondary, other
addresses
[object]
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
object
Data about the components comprising an address.
city
nullablestring
The full city name
region
nullablestring
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
nullablestring
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code
primary
boolean
When true, identifies the address as the primary address on an account.
item
object
Metadata about the Item.
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
nullablestring
The Plaid Institution ID associated with the Item. Field is null for Items created via Same Day Micro-deposits.
webhook
nullablestring
The URL registered to receive webhooks for the Item.
error
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
available_products
[string]
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
billed_products
[string]
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available_products. Note - billed_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
products
[string]
A list of initialized products for the Item. In almost all cases, this will be the same as the billed_products field. For some products, it is possible for the product to be initialized on an Item but not yet billed (e.g. Assets, before /asset_report/create has been called), in which case the product may appear in products but not in billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consented_products
[string]
A list of products that have gone through consent collection for the Item. Only present for those enabled in the Data Transparency beta. If you are not enrolled in Data Transparency, this field is not used.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consent_expiration_time
nullablestring
The RFC 3339 timestamp after which the consent provided by the end user will expire. Upon consent expiration, the item will enter the ITEM_LOGIN_REQUIRED error state. To circumvent the ITEM_LOGIN_REQUIRED error and maintain continuous consent, the end user can reauthenticate via Link’s update mode in advance of the consent expiration time.
Note - This is only relevant for certain OAuth-based institutions. For all other institutions, this field will be null.

Format: date-time
update_type
string
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication.
background - Item can be updated in the background
user_present_required - Item requires user interaction to be updated

Possible values: background, user_present_required
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "accounts": [
3    {
4      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
5      "balances": {
6        "available": 100,
7        "current": 110,
8        "iso_currency_code": "USD",
9        "limit": null,
10        "unofficial_currency_code": null
11      },
12      "mask": "0000",
13      "name": "Plaid Checking",
14      "official_name": "Plaid Gold Standard 0% Interest Checking",
15      "owners": [
16        {
17          "addresses": [
18            {
19              "data": {
20                "city": "Malakoff",
21                "country": "US",
22                "postal_code": "14236",
23                "region": "NY",
24                "street": "2992 Cameron Road"
25              },
26              "primary": true
27            },
28            {
29              "data": {
30                "city": "San Matias",
31                "country": "US",
32                "postal_code": "93405-2255",
33                "region": "CA",
34                "street": "2493 Leisure Lane"
35              },
36              "primary": false
37            }
38          ],
39          "emails": [
40            {
41              "data": "accountholder0@example.com",
42              "primary": true,
43              "type": "primary"
44            },
45            {
46              "data": "accountholder1@example.com",
47              "primary": false,
48              "type": "secondary"
49            },
50            {
51              "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
52              "primary": false,
53              "type": "other"
54            }
55          ],
56          "names": [
57            "Alberta Bobbeth Charleson"
58          ],
59          "phone_numbers": [
60            {
61              "data": "1112223333",
62              "primary": false,
63              "type": "home"
64            },
65            {
66              "data": "1112224444",
67              "primary": false,
68              "type": "work"
69            },
70            {
71              "data": "1112225555",
72              "primary": false,
73              "type": "mobile"
74            }
75          ]
76        }
77      ],
78      "subtype": "checking",
79      "type": "depository"
80    },
81    {
82      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
83      "balances": {
84        "available": 200,
85        "current": 210,
86        "iso_currency_code": "USD",
87        "limit": null,
88        "unofficial_currency_code": null
89      },
90      "mask": "1111",
91      "name": "Plaid Saving",
92      "official_name": "Plaid Silver Standard 0.1% Interest Saving",
93      "owners": [
94        {
95          "addresses": [
96            {
97              "data": {
98                "city": "Malakoff",
99                "country": "US",
100                "postal_code": "14236",
101                "region": "NY",
102                "street": "2992 Cameron Road"
103              },
104              "primary": true
105            },
106            {
107              "data": {
108                "city": "San Matias",
109                "country": "US",
110                "postal_code": "93405-2255",
111                "region": "CA",
112                "street": "2493 Leisure Lane"
113              },
114              "primary": false
115            }
116          ],
117          "emails": [
118            {
119              "data": "accountholder0@example.com",
120              "primary": true,
121              "type": "primary"
122            },
123            {
124              "data": "accountholder1@example.com",
125              "primary": false,
126              "type": "secondary"
127            },
128            {
129              "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
130              "primary": false,
131              "type": "other"
132            }
133          ],
134          "names": [
135            "Alberta Bobbeth Charleson"
136          ],
137          "phone_numbers": [
138            {
139              "data": "1112223333",
140              "primary": false,
141              "type": "home"
142            },
143            {
144              "data": "1112224444",
145              "primary": false,
146              "type": "work"
147            },
148            {
149              "data": "1112225555",
150              "primary": false,
151              "type": "mobile"
152            }
153          ]
154        }
155      ],
156      "subtype": "savings",
157      "type": "depository"
158    }
159  ],
160  "item": {
161    "available_products": [
162      "balance",
163      "investments"
164    ],
165    "billed_products": [
166      "assets",
167      "auth",
168      "identity",
169      "liabilities",
170      "transactions"
171    ],
172    "consent_expiration_time": null,
173    "error": null,
174    "institution_id": "ins_3",
175    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
176    "update_type": "background",
177    "webhook": "https://www.genericwebhookurl.com/webhook"
178  },
179  "request_id": "3nARps6TOYtbACO"
180}
Was this helpful?

/identity/match

This feature is in currently in beta; please reach out to your Plaid Account Manager if you would like it enabled.

Retrieve identity match score

The /identity/match endpoint generates a match score, which indicates how well the provided identity data matches the identity information on file with the account holder's financial institution.
This request may take some time to complete if Identity was not specified as an initial product when creating the Item. This is because Plaid must communicate directly with the institution to retrieve the data.

identity/match

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
user
object
The user's legal name, phone number, email address and address used to perform fuzzy match. If Financial Account Matching is enabled in the Identity Verification product, leave this field empty to automatically match against PII collected from the Identity Verification checks.
legal_name
string
The user's full legal name.
phone_number
string
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis.
email_address
string
The user's email address.
address
object
Data about the components comprising an address.
city
string
The full city name
region
string
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
string
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
string
The ISO 3166-1 alpha-2 country code
options
object
An optional object to filter /identity/match results
account_ids
[string]
An array of account_ids to perform fuzzy match
Select Language
1// Match identity provided by client against bank/account identity
2const request: IdentityMatchRequest = {
3  access_token: accessToken,
4};
5try {
6  const response = await plaidClient.identityMatch(request);
7  const accounts = response.data.accounts
8  for(var account of accounts) {
9        const legalNameScore = account.legal_name
10        const phoneScore = account.phone_number
11        const emailScore = account.email_address
12        const addressScore = account.address
13        if (legalNameScore != null) {
14          const legalNameScoreValue = legalNameScore.score
15        }
16    }
17} catch (error) {
18  // handle error
19}
identity/match

Response fields and example

accounts
[object]
The accounts for which Identity match has been requested
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullablenumber
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullablenumber
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullablenumber
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullablestring
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
legal_name
nullableobject
Score found by matching name provided by the API with the name on the account at the financial institution. If the account contains multiple owners, the maximum match score is filled.
score
nullableinteger
Match score for name. 100 is a perfect score, 99-85 means a strong match, 84-70 is a partial match, any score less than 70 is a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the name is missing from either the API or financial institution, this is null.
is_first_name_or_last_name_match
nullableboolean
first or last name completely matched, likely a family member
is_nickname_match
nullableboolean
nickname matched, example Jennifer and Jenn.
is_business_name_detected
deprecatednullableboolean
Is true if the name on either of the names that was matched for the score contained strings indicative of a business name, such as "CORP", "LLC", "INC", or "LTD". A true result generally indicates the entity is a business. However, a false result does not mean the entity is not a business, as some businesses do not use these strings in the names used for their financial institution accounts.
phone_number
nullableobject
Score found by matching phone number provided by the API with the phone number on the account at the financial institution. 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled.
score
nullableinteger
Match score for normalized phone number. 100 is a perfect match, 99-70 is a partial match (matching the same phone number with extension against one without extension etc.), anything below 70 is considered a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the phone number is missing from either the API or financial institution, this is null.
email_address
nullableobject
Score found by matching email provided by the API with the email on the account at the financial institution. 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled.
score
nullableinteger
Match score for normalized email. 100 is a perfect match, 99-70 is a partial match (matching the same email with different '+' extensions), anything below 70 is considered a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the email is missing from either the API or financial institution, this is null.
address
nullableobject
Score found by matching address provided by the API with the address on the account at the financial institution. The score can range from 0 to 100 where 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled.
score
nullableinteger
Match score for address. 100 is a perfect match, 99-90 is a strong match, 89-80 is a partial match, anything below 80 is considered a weak match. Typically, the match threshold should be set to a score of 80 or higher. If the address is missing from either the API or financial institution, this is null.
is_postal_code_match
nullableboolean
postal code was provided for both and was a match
item
object
Metadata about the Item.
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
nullablestring
The Plaid Institution ID associated with the Item. Field is null for Items created via Same Day Micro-deposits.
webhook
nullablestring
The URL registered to receive webhooks for the Item.
error
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
available_products
[string]
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
billed_products
[string]
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available_products. Note - billed_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
products
[string]
A list of initialized products for the Item. In almost all cases, this will be the same as the billed_products field. For some products, it is possible for the product to be initialized on an Item but not yet billed (e.g. Assets, before /asset_report/create has been called), in which case the product may appear in products but not in billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consented_products
[string]
A list of products that have gone through consent collection for the Item. Only present for those enabled in the Data Transparency beta. If you are not enrolled in Data Transparency, this field is not used.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consent_expiration_time
nullablestring
The RFC 3339 timestamp after which the consent provided by the end user will expire. Upon consent expiration, the item will enter the ITEM_LOGIN_REQUIRED error state. To circumvent the ITEM_LOGIN_REQUIRED error and maintain continuous consent, the end user can reauthenticate via Link’s update mode in advance of the consent expiration time.
Note - This is only relevant for certain OAuth-based institutions. For all other institutions, this field will be null.

Format: date-time
update_type
string
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication.
background - Item can be updated in the background
user_present_required - Item requires user interaction to be updated

Possible values: background, user_present_required
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "accounts": [
3    {
4      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
5      "balances": {
6        "available": 100,
7        "current": 110,
8        "iso_currency_code": "USD",
9        "limit": null,
10        "unofficial_currency_code": null
11      },
12      "mask": "0000",
13      "name": "Plaid Checking",
14      "official_name": "Plaid Gold Standard 0% Interest Checking",
15      "legal_name": {
16        "score": 90,
17        "is_nickname_match": true,
18        "is_first_name_or_last_name_match": true,
19        "is_business_name_detected": false
20      },
21      "phone_number": {
22        "score": 100
23      },
24      "email_address": {
25        "score": 100
26      },
27      "address": {
28        "score": 100,
29        "is_postal_code_match": true
30      },
31      "subtype": "checking",
32      "type": "depository"
33    },
34    {
35      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
36      "balances": {
37        "available": 200,
38        "current": 210,
39        "iso_currency_code": "USD",
40        "limit": null,
41        "unofficial_currency_code": null
42      },
43      "mask": "1111",
44      "name": "Plaid Saving",
45      "official_name": "Plaid Silver Standard 0.1% Interest Saving",
46      "legal_name": {
47        "score": 30,
48        "is_first_name_or_last_name_match": false
49      },
50      "phone_number": {
51        "score": 100
52      },
53      "email_address": null,
54      "address": {
55        "score": 100,
56        "is_postal_code_match": true
57      },
58      "subtype": "savings",
59      "type": "depository"
60    }
61  ],
62  "item": {
63    "available_products": [
64      "balance",
65      "investments"
66    ],
67    "billed_products": [
68      "assets",
69      "auth",
70      "identity",
71      "liabilities",
72      "transactions"
73    ],
74    "consent_expiration_time": null,
75    "error": null,
76    "institution_id": "ins_3",
77    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
78    "update_type": "background",
79    "webhook": "https://www.genericwebhookurl.com/webhook"
80  },
81  "request_id": "3nARps6TOYtbACO"
82}
Was this helpful?

Webhooks (beta)

This feature is in currently in beta; please reach out to your Plaid Account Manager if you would like it enabled.

DEFAULT_UPDATE

Fired when a change to identity data has been detected on an Item. Items are checked for identity updates every 30-90 days. We recommend that upon receiving this webhook you make another call to /identity/get to fetch the user's latest identity data.

webhook_type
string
IDENTITY
webhook_code
string
DEFAULT_UPDATE
item_id
string
The item_id of the Item associated with this webhook, warning, or error
account_ids_with_updated_identity
object
An object with keys of account_id's that are mapped to their respective identity attributes that changed.
Example: { "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58": ["PHONES"] }
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "IDENTITY",
3  "webhook_code": "DEFAULT_UPDATE",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "account_ids_with_updated_identity": {
6    "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp": [
7      "ADDRESSES"
8    ]
9  },
10  "error": null,
11  "environment": "production"
12}
Was this helpful?

resources

Plaid resources

External resources to help build your Plaid integration

In addition to the docs here, Plaid has a collection of tools, sample code, SDKs, and videos to help you build your Plaid integration.

Sample apps

Our GitHub contains a number of sample apps to help you get started using Plaid!

Quickstart

Official Plaid Quickstart, using React, available in NodeJS, Python, Ruby, Java, and Go

Tiny Quickstart

A Plaid implementation in 150 lines. Available in JavaScript, Next.Js, React, and React Native frontends.

Personal Finances

Usages of Transactions, Assets, and Liabilities APIs, using NodeJS and React

Personal Finances - Hosted

A fully hosted, live version of the Personal Finances sample app

Account Funding

Auth, Identity, and Balance APIs for money movement, in NodeJS and React

Account Funding in Europe

Account funding using the Payment Initiation API, using NodeJS and React

Transfer

Subscription payments with the Transfer API, using NodeJS and React

Identity Verification Quickstart

See Plaid Identity Verification in action! (NodeJS only)

Income

A lending app using the Income API, using NodeJS and React

Plaid Academy videos

Our YouTube series, Plaid Academy, is a fun and engaging way to learn about using Plaid.

Getting started with the Plaid API

Learn the essential concepts of the Plaid API and make your first API calls.

Plaid and Postman full tutorial

Make your first API calls with Plaid -- without ever writing a line of code!

Plaid OAuth JavaScript tutorial

Every Plaid integration needs to support OAuth. Learn how and why in this video.

Plaid webhooks

Find out more about webhooks in this video.

Plaid Auth full tutorial

A comprehensive guide to adding Plaid Auth to your app.

Plaid Transactions full tutorial

A comprehensive guide to adding Plaid Transactions to your app.

Plaid Identity Verification Quickstart demo

A video tour of the Identity Verification Quickstart app.

Plaid in 3 Minutes

An overview of the Plaid API -- what it does and how to use it.

Plaid and Postman in 3 Minutes

Making calls to the Plaid API without code -- the version for busy people.

Income in 3 Minutes

Get an overview of how to integrate with the Income API in just 3 minutes!

Transfer UI in 3 minutes

Get an overview of how to integrate with the Transfer UI API, in just 3 minutes!

Identity Verification in 3 minutes

Get an overview of how to integrate with Identity Verification, in just 3 minutes!

Monitor in 3 minutes

Get an overview of how to integrate with Monitor, in just 3 minutes!

Auth in 3 minutes

Get an overview of how to integrate with Auth, in just 3 minutes!

Signal in 3 minutes

Get an overview of how to integrate with Signal, in just 3 minutes!

Transactions in 3 minutes

Learn all about Transactions, in just 3 minutes!

Enrich in 3 minutes

Learn about using Enrich with your own transactions, in just 3 minutes!

Configuring the products array

Learn to configure the products array for maximum conversion

Interactive tutorial

Want to get started building a Plaid-powered application directly in your browser? You can do that with the Plaid Basics interactive tutorial.

Integration guides

Plaid offers several PDF guides with information from the docs provided in a step-by-step walkthrough format.

Launch checklist

The Launch checklist provides a list of steps to help make sure your app is Plaid-optimized and production ready.

SDKs

For information about official and community supported libraries for both the Plaid API and the Link frontend component, see libraries.

Postman

The Postman Collection provides an easy, no-code way to explore the API.

OpenAPI file

The Plaid OpenAPI file is available on GitHub. This file describes the Plaid API in a standardized way suitable for usage with tools for testing, client library generation, and other purposes that ingest OpenAPI/Swagger definition files.

Test data libraries

Plaid maintains a repo of configuration objects suitable for usage as custom Sandbox users to help you test apps in Sandbox.

Credit attributes library

For the Assets and Income products, Plaid maintains a Credit attributes library of scripts that can be used to derive various useful attributes from an Asset Report or Bank Income.

Enrich test transaction library

For testing Enrich, Plaid provides a list of Sandbox-compatible Enrich transactions.

Community

You can join the Plaid Developer Community on Discord or ask questions on Stack Overflow.

Partnerships

Plaid partners can unlock additional functionality, deepen your integrations, or even build out your integration for you! For more information, see the Partner directory.

Third-party resources

Several third party developers have built resources to help you integrate with Plaid. Note that these resources are not built or supported by Plaid, and inclusion of a resource on the list below does not constitute an endorsement by Plaid or indicate that Plaid has evaluated the resource for correctness, security, or anything else.

If you have a third-party resource you'd like to be featured on this list, DM us @plaiddev on Twitter, or reach out to an admin on the Plaid Developer Discord.

  • How to Build a Fintech app on AWS using the Plaid API and the accompanying sample app demonstrates how to build a Plaid app on AWS, using the latest Transactions Sync API. The app and tutorial incorporate AWS Lambda for webhook handling and Amazon Cognito for authentication.
  • CodeSandbox has several sample apps that use Plaid.
  • WebhookDB has a tutorial showing how to use their service to more easily manage Plaid webhooks.
  • Venice is a platform that handles common infrastructure requirements for Plaid deployments, including ETL pipelines, token management, webhook handling, and more, allowing you to focus on business logic.
  • The CloudQuery Plaid plugin extracts data from Plaid and loads it into any supported CloudQuery destination, such as PostgreSQL, Snowflake, BigQuery, or S3.

link web

Link Web SDK

Reference for integrating with the Link JavaScript SDK and React SDK

Prefer to learn with code examples? Check out our GitHub repo with working example Link implementations for both JavaScript and React.

Installation

Select group for content switcher

Include the Plaid Link initialize script on each page of your site. It must always be loaded directly from https://cdn.plaid.com, rather than included in a bundle or hosted yourself.

1<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>

CSP directives

If you are using a Content Security Policy (CSP), use the following directives to allow Link traffic:

Select Language
1default-src https://cdn.plaid.com/
2script-src https://cdn.plaid.com/link/v2/stable/link-initialize.js
3frame-src https://cdn.plaid.com/
4connect-src https://production.plaid.com/

If using Sandbox or Development instead of production, make sure to update the connect-src directive to point to the appropriate server (https://sandbox.plaid.com or https://development.plaid.com).

Create

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the Consent Pane view, calling exit will close Link, and calling destroy will clean up the iframe.
When using the React SDK, this method is called usePlaidLink and returns an object with four values, open, exit, ready, and error. The values open and exit behave as described above. ready is a passthrough for onLoad and will be true when Link is ready to be opened. error is populated only if Plaid fails to load the Link JavaScript. There is no separate method to destroy Link in the React SDK, as unmount will automatically destroy the Link instance.
Note: Control whether or not your Link integration uses the Account Select view from the Dashboard.

create
token
string
Specify a link_token to authenticate your app with Link. This is a short lived, one-time use token that should be unique for each Link session. In addition to the primary flow, a link_token can be configured to launch Link in update mode. See the /link/token/create endpoint for a full list of configurations.
onSuccess
callback
A function that is called when a user successfully links an Item. The function should expect two arguments, the public_token and a metadata object. See onSuccess.
onExit
callback
A function that is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The function should expect two arguments, a nullable error object and a metadata object. See onExit.
onEvent
callback
A function that is called when a user reaches certain points in the Link flow. The function should expect two arguments, an eventName string and a metadata object. See onEvent.
onLoad
callback
A function that is called when the Link module has finished loading. Calls to plaidLinkHandler.open() prior to the onLoad callback will be delayed until the module is fully loaded.
receivedRedirectUri
string
A receivedRedirectUri is required to support OAuth authentication flows when re-launching Link on a mobile device.
key
deprecatedstring
The public_key is no longer used for new implementations of Link. If your integration is still using a public_key, see the migration guide to upgrade to using a link_token. See the maintenance guide to troubleshoot any public_key issues.
Select Language
1// The usePlaidLink hook manages Plaid Link creation
2// It does not return a destroy function;
3// instead, on unmount it automatically destroys the Link instance
4const config: PlaidLinkOptions = {
5  onSuccess: (public_token, metadata) => {}
6  onExit: (err, metadata) => {}
7  onEvent: (eventName, metadata) => {}
8  token: 'GENERATED_LINK_TOKEN',
9  //required for OAuth; if not using OAuth, set to null or omit:
10  receivedRedirectUri: window.location.href,
11};
12
13const { open, exit, ready } = usePlaidLink(config);

onSuccess

The onSuccess callback is called when a user successfully links an Item. It takes two arguments: the public_token and a metadata object.

onSuccess
public_token
string
Displayed once a user has successfully linked their Item.
metadata
object
Displayed once a user has successfully linked their Item.
institution
nullableobject
An institution object. If the Item was created via Same-Day micro-deposit verification, will be null.
name
string
The full institution name, such as 'Wells Fargo'
institution_id
string
The Plaid institution identifier
accounts
object
A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, accounts will only include selected accounts.
id
string
The Plaid account_id
name
string
The official account name
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts. It may also not match the mask that the bank displays to the user.
type
string
The account type. See the Account schema for a full list of possible values
subtype
string
The account subtype. See the Account schema for a full list of possible values
verification_status
nullablestring
Indicates an Item's micro-deposit-based verification status. Possible values are:
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the two amounts.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.
null: micro-deposit-based verification is not being used for the Item.
class_type
nullablestring
If micro-deposit verification is being used, indicates whether the account being verified is a business or personal account.
account
deprecatednullableobject
Deprecated. Use accounts instead.
link_session_id
string
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
transfer_status
nullablestring
The status of a transfer. Returned only when Transfer UI is implemented.
  • COMPLETE – The transfer was completed.
  • INCOMPLETE – The transfer could not be completed. For help, see Troubleshooting transfers.


Possible values: COMPLETE, INCOMPLETE
Select Language
1import {
2  PlaidLinkOnSuccess,
3  PlaidLinkOnSuccessMetadata,
4} from 'react-plaid-link';
5
6const onSuccess = useCallback<PlaidLinkOnSuccess>(
7  (public_token: string, metadata: PlaidLinkOnSuccessMetadata) => {
8    // log and save metadata
9    // exchange public token
10    fetch('//yourserver.com/exchange-public-token', {
11      method: 'POST',
12      headers: {
13        'Content-Type': 'application/json',
14      },
15      body: {
16        public_token,
17      },
18    });
19  },
20  [],
21);
1{
2  institution: {
3    name: 'Wells Fargo',
4    institution_id: 'ins_4'
5  },
6  accounts: [
7    {
8      id: 'ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy',
9      name: 'Plaid Checking',
10      mask: '0000',
11      type: 'depository',
12      subtype: 'checking',
13      verification_status: ''
14    },
15    {
16      id: '9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4',
17      name: 'Plaid Saving',
18      mask: '1111',
19      type: 'depository',
20      subtype: 'savings'
21    }
22    ...
23  ],
24  link_session_id: '79e772be-547d-4c9c-8b76-4ac4ed4c441a'
25}

onExit

The onExit callback is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. It takes two arguments, a nullable error object and a metadata object. The metadata parameter is always present, though some values may be null.

onExit
error
nullableobject
A nullable object that contains the error type, code, and message of the error that was last encountered by the user. If no error was encountered, error will be null.
error_type
String
A broad categorization of the error.
error_code
String
The particular error code. Each error_type has a specific set of error_codes.
error_message
String
A developer-friendly representation of the error code.
display_message
nullableString
A user-friendly representation of the error code. null if the error is not related to user action. This may change over time and is not safe for programmatic use.
metadata
object
Displayed once a user has successfully linked their Item.
institution
nullableobject
An institution object. If the Item was created via Same-Day micro-deposit verification, will be null.
name
string
The full institution name, such as Wells Fargo
institution_id
string
The Plaid institution identifier
status
string
The point at which the user exited the Link flow. One of the following values.
requires_questions
User prompted to answer security questions
requires_selections
User prompted to answer multiple choice question(s)
requires_code
User prompted to provide a one-time passcode
choose_device
User prompted to select a device on which to receive a one-time passcode
requires_credentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution
requires_account_selection
User prompted to select one or more financial accounts to share
requires_oauth
User prompted to enter an OAuth flow
institution_not_found
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
link_session_id
string
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
request_id
string
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation.
Select Language
1import {
2  PlaidLinkOnExit,
3  PlaidLinkOnExitMetadata,
4  PlaidLinkError,
5} from 'react-plaid-link';
6
7const onExit = useCallback<PlaidLinkOnExit>(
8  (error: PlaidLinkError, metadata: PlaidLinkOnExitMetadata) => {
9    // log and save error and metadata
10    // handle invalid link token
11    if (error != null && error.error_code === 'INVALID_LINK_TOKEN') {
12      // generate new link token
13    }
14    // to handle other error codes, see https://plaid.com/docs/errors/
15  },
16  [],
17);
1{
2  error_type: 'ITEM_ERROR',
3  error_code: 'INVALID_CREDENTIALS',
4  error_message: 'the credentials were not correct',
5  display_message: 'The credentials were not correct.',
6}
1{
2  institution: {
3    name: 'Wells Fargo',
4    institution_id: 'ins_4'
5  },
6  status: 'requires_credentials',
7  link_session_id: '36e201e0-2280-46f0-a6ee-6d417b450438',
8  request_id: '8C7jNbDScC24THu'
9}

onEvent

The onEvent callback is called at certain points in the Link flow. It takes two arguments, an eventName string and a metadata object.
The metadata parameter is always present, though some values may be null. Note that new eventNames, metadata keys, or view names may be added without notice.
The onEvent callback is not guaranteed to fire exactly at the time of a user action in Link. In general, the OPEN event will fire in real time; subsequent events will fire at the end of the Link flow, along with the onSuccess or onExit callback. If you need to determine the exact time when an event happened, use the timestamp in the metadata.
The following callback events are stable, which means that they will not be deprecated or changed: OPEN, EXIT, HANDOFF, SELECT_INSTITUTION, ERROR, BANK_INCOME_INSIGHTS_COMPLETED, IDENTITY_VERIFICATION_PASS_SESSION, IDENTITY_VERIFICATION_FAIL_SESSION. The remaining callback events are informational and subject to change.

onEvent
eventName
string
A string representing the event that has just occurred in the Link flow.
BANK_INCOME_INSIGHTS_COMPLETED
The user has completed the Assets and Bank Income Insights flow.
CLOSE_OAUTH
The user closed the third-party website or mobile app without completing the OAuth flow.
ERROR
A recoverable error occurred in the Link flow, see the error_code metadata.
EXIT
The user has exited without completing the Link flow and the onExit callback is fired.
FAIL_OAUTH
The user encountered an error while completing the third-party's OAuth login flow.
HANDOFF
The user has exited Link after successfully linking an Item.
IDENTITY_VERIFICATION_START_STEP
The user has started a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_PASS_STEP
The user has passed a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_FAIL_STEP
The user has failed a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_PENDING_REVIEW_STEP
The user has reached the pending review state.
IDENTITY_VERIFICATION_CREATE_SESSION
The user has started a new Identity Verification session.
IDENTITY_VERIFICATION_RESUME_SESSION
The user has resumed an existing Identity Verification session.
IDENTITY_VERIFICATION_PASS_SESSION
The user has successfully completed their Identity Verification session.
IDENTITY_VERIFICATION_FAIL_SESSION
The user has failed their Identity Verification session.
IDENTITY_VERIFICATION_PENDING_REVIEW_SESSION
The user has completed their Identity Verification session, which is now in a pending review state.
IDENTITY_VERIFICATION_OPEN_UI
The user has opened the UI of their Identity Verification session.
IDENTITY_VERIFICATION_RESUME_UI
The user has resumed the UI of their Identity Verification session.
IDENTITY_VERIFICATION_CLOSE_UI
The user has closed the UI of their Identity Verification session.
MATCHED_SELECT_INSTITUTION
The user selected an institution that was presented as a matched institution. This event can be emitted either during the Returning User Experience flow or if the institution's routing_number was provided when calling /link/token/create. To distinguish between the two scenarios, see metadata.match_reason.
MATCHED_SELECT_VERIFY_METHOD
The user selected a verification method for a matched institution. This event is emitted during the Returning User Experience flow.
OPEN
The user has opened Link.
OPEN_MY_PLAID
The user has opened my.plaid.com. This event is only sent when Link is initialized with Assets as a product
OPEN_OAUTH
The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.
SEARCH_INSTITUTION
The user has searched for an institution.
SELECT_AUTH_TYPE
The user has chosen whether to Link instantly or manually (i.e., with micro-deposits). This event emits the selection metadata to indicate the user's selection.
SELECT_BRAND
The user selected a brand, e.g. Bank of America. The SELECT_BRAND event is only emitted for large financial institutions with multiple online banking portals.
SELECT_DEGRADED_INSTITUTION
The user selected an institution with a DEGRADED health status and was shown a corresponding message.
SELECT_DOWN_INSTITUTION
The user selected an institution with a DOWN health status and was shown a corresponding message.
SELECT_INSTITUTION
The user selected an institution.
SUBMIT_ACCOUNT_NUMBER
The user has submitted an account number. This event emits the account_number_mask metadata to indicate the mask of the account number the user provided.
SUBMIT_CREDENTIALS
The user has submitted credentials.
SUBMIT_DOCUMENTS
The user is being prompted to submit documents for an Income verification flow.
SUBMIT_DOCUMENTS_ERROR
The user encountered an error when submitting documents for an Income verification flow.
SUBMIT_DOCUMENTS_SUCCESS
The user has successfully submitted documents for an Income verification flow.
SUBMIT_MFA
The user has submitted MFA.
SUBMIT_ROUTING_NUMBER
The user has submitted routing number. This event emits the routing_number metadata to indicate user's routing number.
TRANSITION_VIEW
The TRANSITION_VIEW event indicates that the user has moved from one view to the next.
VIEW_DATA_TYPES
The user has viewed data types on the data transparency consent pane.
metadata
object
An object containing information about the event.
account_number_mask
nullablestring
The account number mask extracted from the user-provided account number. If the user-inputted account number is four digits long, account_number_mask is empty. Emitted by SUBMIT_ACCOUNT_NUMBER.
error_type
nullablestring
The error type that the user encountered. Emitted by: ERROR, EXIT.
error_code
nullablestring
The error code that the user encountered. Emitted by ERROR, EXIT.
error_message
nullablestring
The error message that the user encountered. Emitted by: ERROR, EXIT.
exit_status
nullablestring
The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT
institution_id
nullablestring
The ID of the selected institution. Emitted by: all events.
institution_name
nullablestring
The name of the selected institution. Emitted by: all events.
institution_search_query
nullablestring
The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.
is_update_mode
nullablestring
Indicates if the current Link session is an update mode session. Emitted by: OPEN.
match_reason
nullablestring
The reason this institution was matched, which will be either returning_user or routing_number. Emitted by: MATCHED_SELECT_INSTITUTION
routing_number
nullablestring
The routing number submitted by user at the micro-deposits routing number pane. Emitted by SUBMIT_ROUTING_NUMBER.
mfa_type
nullablestring
If set, the user has encountered one of the following MFA types: code, device, questions, selections. Emitted by: SUBMIT_MFA and TRANSITION_VIEW when view_name is MFA
view_name
nullablestring
The name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW.
ACCEPT_TOS
The view showing Terms of Service in the identity verification flow.
CONNECTED
The user has connected their account.
CONSENT
We ask the user to consent to the privacy policy.
CREDENTIAL
Asking the user for their account credentials.
DATA_TRANSPARENCY
We disclose the data types being shared.
DATA_TRANSPARENCY_CONSENT
We ask the user to consent to the privacy policy and disclose data types being shared.
DOCUMENTARY_VERIFICATION
The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor).
ERROR
An error has occurred.
EXIT
Confirming if the user wishes to close Link.
KYC_CHECK
The view representing the "know your customer" step in the identity verification flow.
LOADING
Link is making a request to our servers.
MATCHED_CONSENT
We ask the matched user to consent to the privacy policy and SMS terms.
MATCHED_CREDENTIAL
We ask the matched user for their account credentials to a matched institution.
MATCHED_MFA
We ask the matched user for MFA authentication to verify their identity.
MFA
The user is asked by the institution for additional MFA authentication.
NUMBERS
The user is asked to insert their account and routing numbers.
OAUTH
The user is informed they will authenticate with the financial institution via OAuth.
RECAPTCHA
The user was presented with a Google reCAPTCHA to verify they are human.
RISK_CHECK
The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor).
SCREENING
The watchlist screening step in the identity verification flow.
SELECT_ACCOUNT
We ask the user to choose an account.
SELECT_AUTH_TYPE
The user is asked to choose whether to Link instantly or manually (i.e., with micro-deposits).
SELECT_BRAND
The user is asked to select a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.
SELECT_INSTITUTION
We ask the user to choose their institution.
SELFIE_CHECK
The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.
UPLOAD_DOCUMENTS
The user is asked to upload documents (for Income verification).
VERIFY_SMS
The SMS verification step in the identity verification flow.
request_id
string
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
link_session_id
string
The link_session_id is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: all events.
timestamp
string
An ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z. Emitted by: all events.
selection
nullablestring
Either the verification method for a matched institution selected by the user or the Auth Type Select flow type selected by the user. If selection is used to describe selected verification method, then possible values are phoneotp or password; if selection is used to describe the selected Auth Type Select flow, then possible values are flow_type_manual or flow_type_instant. Emitted by: MATCHED_SELECT_VERIFY_METHOD and SELECT_AUTH_TYPE.
Select Language
1import {
2  PlaidLinkOnEvent,
3  PlaidLinkOnEventMetadata,
4  PlaidLinkStableEvent,
5} from 'react-plaid-link';
6
7const onEvent = useCallback<PlaidLinkOnEvent>(
8  (
9    eventName: PlaidLinkStableEvent | string,
10    metadata: PlaidLinkOnEventMetadata,
11  ) => {
12    // log eventName and metadata
13  },
14  [],
15);
1{
2  error_type: 'ITEM_ERROR',
3  error_code: 'INVALID_CREDENTIALS',
4  error_message: 'the credentials were not correct',
5  exit_status: null,
6  institution_id: 'ins_4',
7  institution_name: 'Wells Fargo',
8  institution_search_query: 'wellsf',
9  mfa_type: null,
10  view_name: 'ERROR'
11  request_id: 'm8MDnv9okwxFNBV',
12  link_session_id: '30571e9b-d6c6-42ee-a7cf-c34768a8f62d',
13  timestamp: '2017-09-14T14:42:19.350Z',
14  selection: null,
15}

open()

Calling open will display the Consent Pane view to your user, starting the Link flow. Once open is called, you will begin receiving events via the onEvent callback.

Select Language
1const { open, exit, ready } = usePlaidLink(config);
2
3// Open Link
4if (ready) {
5  open();
6}

exit()

The exit function allows you to programmatically close Link. Calling exit will trigger either the onExit or onSuccess callbacks.
The exit function takes a single, optional argument, a configuration Object.

exit
force
boolean
If true, Link will exit immediately. If false, or the option is not provided, an exit confirmation screen may be presented to the user.
Select Language
1const { open, exit, ready } = usePlaidLink(config);
2
3// Graceful exit - Link may display a confirmation screen
4// depending on how far the user is in the flow
5exit();
Select Language
1const { open, exit, ready } = usePlaidLink(config);
2
3// Force exit - Link exits immediately
4exit({ force: true });

destroy()

The destroy function allows you to destroy the Link handler instance, properly removing any DOM artifacts that were created by it. Use destroy() when creating new replacement Link handler instances in the onExit callback.

Select Language
1// On unmount usePlaidLink hook automatically destroys any
2// existing link instance

OAuth

Using Plaid Link with an OAuth flow requires some additional setup instructions. For details, see the OAuth Guide.

Supported browsers

Plaid officially supports Link on the latest versions of Chrome, Firefox, Safari, and Edge. Browsers are supported on Windows, Mac, Linux, iOS, and Android. Previous browser versions are also supported, as long as they are actively maintained; Plaid does not support browser versions that are no longer receiving patch updates, or that have been assigned official end of life (EOL) or end of support (EOS) status.

Ad-blocking software is not officially supported with Link web, and some ad-blockers have known to cause conflicts with Link.

Example code in Plaid Pattern

For a real-life example of using Plaid Link for React, see LaunchLink.tsx. This file illustrates the code for implementation of Plaid Link for React for the Node-based Plaid Pattern sample app.

link returning user

Introduction to the returning user experience

Build a faster Link flow for existing Plaid users

The returning user experience (RUX) streamlines onboarding for users who have already connected a financial account with Plaid. If your application collects the user’s phone number and/or email address before the user enters Plaid Link, you may enable the returning user experience by supplying these values in the user object when calling /link/token/create. These fields will not be stored beyond the lifetime of the Link token (4 hours), but will be hashed and compared against hashed data to determine whether Plaid can recognize the user as having linked Items in the past.

Boosting previously connected institutions

The returning user experience can be enabled to create a streamlined Link experience for users when Plaid already knows which institutions the user has previously connected.

When a user.phone_number is provided via the user request object in the /link/token/create endpoint, Plaid will match that data against previously connected accounts. On the Institution Select screen, institutions that a user has already connected with Plaid will be displayed at the top of the list. In testing, showing previously connected institutions at the top can help boost conversion.

Note that providing an email address, without a phone number, will not enable institution boosting. For best results, and to enable more RUX flows, it is recommended to provide a phone number and email address for each user whenever possible.

Faster account verification

In addition to boosting previously connected institutions to the top of the list, there are two flows that a returning user could encounter to streamline the verification process depending on the user data (phone number and/or email address) that you pass to Plaid via /link/token/create and institution eligibility. Both of these flows present the returning user with the institutions they have previously connected, which helps to streamline the institution selection process.

Not all financial institutions are compatible with pre-matched or pre-authenticated RUX. For more details, contact your Plaid Account Manager or file a Support request.

Pre-authenticated RUX
Returning User Pre-Authenticated Flow in Plaid Link

The pre-authenticated RUX flow is available for Auth, Balance, Identity, Transfer, Bank Income, Transactions, Assets, Investments, Liabilities, and Signal. To use pre-authenticated RUX, pass user.phone_number and user.email_address into the user request object in the /link/token/create endpoint. If both a user.phone_number and a user.email_address are matched, and the selected institution is eligible for RUX, the user will be prompted to enter a one-time passcode that’s sent to their mobile device instead of entering a username and password. The pre-authenticated RUX flow may not be offered if Plaid flags the session as requiring additional risk mitigation.

The pre-authenticated RUX flow is not enabled by default. To get started with pre-authenticated RUX, contact your Plaid Account Manager or file a support ticket via the Dashboard.

Pre-matched RUX
Returning User Pre-Matched Flow in Plaid Link

The pre-matched RUX flow is available for Auth, Balance, Identity, Bank Income, Transactions, Assets, Investments, Liabilities, and Signal. This experience is available to all Plaid developers by default, and requires a user.phone_number to be passed into the user request object in the /link/token/create endpoint. If a user.phone_number is matched, this flow allows the user to skip entering their username for a given financial institution.

Testing RUX in Sandbox

RUX cannot be used in the Development environment; it must be tested in Production or in the Sandbox. Real email addresses and phone numbers do not work in the Sandbox. Instead, the Sandbox has been seeded with a test user whose phone number and email address may be used to trigger a returning user flow. This user has the following information:

1{
2  "legal_name": "John Doe",
3  "phone_number": "+14155550123",
4  "email_address": "example@plaid.com"
5}

To enable RUX, include the above test user in the user object of the request body when creating a Link token. In Link, the following institutions can be used to test RUX:

  • Platypus Bank RUX Auth (ins_133502) for testing the Pre-authenticated flow
    • The OTP code for the test user is 123456.
  • Platypus Bank RUX Match (ins_133503) for testing the Pre-matched flow
    • The password for the test user is pass_good.

Tracking RUX events

When measuring conversion, RUX flows can be distinguished by their emitting the MATCHED_SELECT_INSTITUTION and MATCHED_SELECT_VERIFY_METHOD events. MATCHED_SELECT_VERIFY_METHOD is emitted only by RUX flows; MATCHED_SELECT_INSTITUTION is used during RUX flows or if a routing_number parameter was supplied to /link/token/create. If you are both using RUX and providing a routing_number and need to distinguish between the two situations, check the metadata.match_reason to ensure that the reason is returning_user.

You can distinguish between different RUX flows via events. The MATCHED_CREDENTIAL view or event indicates that a user experienced the pre-matched RUX flow. The MATCHED_MFA view or event indicates that they experienced the pre-authenticated RUX flow. These events also imply that the user selected a matched institution from the select pane.

For more details, see Link SDK documentation. For more information on tracking Link conversion in general, see Improving Link conversion.

link android

Link Android SDK

Learn how to integrate your app with the Link Android SDK

This guide covers the latest major version of the Link Android SDK, which is version 3.x. If you are using an older version of the SDK, consult the migration guide.

Overview

The Plaid Link SDK is a quick and secure way to link bank accounts to Plaid in your Android app. Link is a drop-in module that handles connecting a financial institution to your app (credential validation, multi-factor authentication, error handling, etc), without passing sensitive personal information to your server.

To get started with Plaid Link for Android, clone the GitHub repository and try out the example application, which provides a reference implementation in both Java and Kotlin. Youʼll want to sign up for free API keys through the Plaid Developer Dashboard to get started.

Examples of Plaid Link for Android

Prefer to learn by watching? A video guide is available for this content.

Initial Android setup

Before writing code using the SDK, you must first perform some setup steps to register your app with Plaid and configure your project.

Register your app ID

To register your Android app ID:

  1. Sign in to the Plaid Dashboard and go to the Team Settings -> API page.
  2. Next to Allowed Android Package Names click Configure then Add New Android Package Name.
  3. Enter your package name, for example com.plaid.example.
  4. Click Save Changes.

Your Android app is now set up and ready to start integrating with the Plaid SDK.

New versions of the Android SDK are released frequently, at least once every few months. You should keep your version up-to-date to provide the best Plaid Link experience in your application.

Update your project plugins

In your root-level (project-level) Gradle file (build.gradle), add rules to include the Android Gradle plugin. Check that you have Google's Maven repository as well.

1buildscript {
2    repositories {
3        // Check that you have the following line (if not, add it):
4        google()  // Google's Maven repository
5        mavenCentral() // Include to import Plaid Link Android SDK
6    }
7    dependencies {
8        // ...
9    }
10}
Add the PlaidLink SDK to your app

In your module (app-level) Gradle file (usually app/build.gradle), add a line to the bottom of the file. The latest version of the PlaidLink SDK is Maven Central and can be found on Maven Central.

1android {
2  defaultConfig {
3    minSdkVersion 21 // or greater
4  }
5
6  // Enable Java 8 support for Link to work
7  compileOptions {
8    sourceCompatibility JavaVersion.VERSION_1_8
9    targetCompatibility JavaVersion.VERSION_1_8
10  }
11}
12
13dependencies {
14  // ...
15  implementation 'com.plaid.link:sdk-core:<insert latest version>'
16}
Enable camera support (Identity Verification only)

If your app uses Identity Verification, a user may need to take a picture of identity documentation or a selfie during the Link flow. To support this workflow, the CAMERA , WRITE_EXTERNAL_STORAGE, RECORD_AUDIO, and MODIFY_AUDIO_SETTINGS permissions need to be added to your application's AndroidManifest.xml. (While Plaid does not record any audio, some older Android devices require these last two permissions to use the camera.) The WRITE_EXTERNAL_STORAGE permission should be limited to < Android 9 (i.e. maxSdk=28). If these permissions are not granted in an app that uses Identity Verification, the app may crash during Link.

Opening Link

Before you can open Link, you need to first create a link_token by calling /link/token/create from your backend. This call should never happen directly from the mobile client, as it risks exposing your API secret. The /link/token/create call must include the android_package_name parameter, which should match the applicationId from your app-level build.gradle file. You can learn more about applicationId in Google's Android developer documentation.

Select group for content switcher
Select Language
1const request: LinkTokenCreateRequest = {
2  user: {
3    client_user_id: 'user-id',
4  },
5  client_name: 'Plaid Test App',
6  products: ['auth', 'transactions'],
7  country_codes: ['GB'],
8  language: 'en',
9  webhook: 'https://sample-web-hook.com',
10  android_package_name: 'com.plaid.example'
11  },
12};
13try {
14  const response = await plaidClient.linkTokenCreate(request);
15  const linkToken = response.data.link_token;
16} catch (error) {
17  // handle error
18}
Create a LinkTokenConfiguration

Each time you open Link, you will need to get a new link_token from your server and create a new LinkTokenConfiguration object with it.

Select Language
1val linkTokenConfiguration = linkTokenConfiguration {
2  token = "LINK_TOKEN_FROM_SERVER"
3}

The Link SDK runs as a separate Activity within your app. In order to return the result to your app, it supports both the standard startActivityForResult and onActivityResult and the ActivityResultContract result APIs.

Select group for content switcher
Register a callback for an Activity Result
Select Language
1private val linkAccountToPlaid =
2registerForActivityResult(OpenPlaidLink()) {
3  when (it) {
4    is LinkSuccess -> /* handle LinkSuccess */
5    is LinkExit -> /* handle LinkExit */
6  }
7}
Open Link
Select Language
1linkAccountToPlaid.launch(linkTokenConfiguration)

At this point, Link will open, and will trigger the onSuccess callback if the user successfully completes the Link flow.

onSuccess

The method is called when a user successfully links an Item. The onSuccess handler returns a LinkConnection class that includes the public_token, and additional Link metadata in the form of a LinkConnectionMetadata class.

onSuccess
publicToken
String
Displayed once a user has successfully linked their Item.
metadata
Object
Displayed once a user has successfully linked their Item.
accounts
List<LinkAccount>
A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, accounts will only include selected accounts.
id
string
The Plaid account_id
name
string
The official account name
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, it may also not match the mask that the bank displays to the user.
subtype
LinkAccountSubtype
The account subtype. See the Account schema for a full list of possible values
type
LinkAccountType
The account type. See the Account schema for a full list of possible values
verification_status
nullablestring
The accounts object includes an Item's micro-deposit verification status. Possible values are:
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the two amounts.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.
null: The Item is not using micro-deposit verification.
institution
nullableobject
An institution object. If the Item was created via Same-Day micro-deposit verification, will be null.
name
string
The full institution name, such as 'Wells Fargo'
institution_id
string
The Plaid institution identifier
linkSessionId
nullableString
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
metadataJson
nullableMap
The data directly returned from the server with no client side changes.
Select Language
1val success = result as LinkSuccess
2
3// Send public_token to your server, exchange for access_token
4val publicToken = success.publicToken
5val metadata = success.metadata
6metadata.accounts.forEach { account ->
7  val accountId = account.id
8  val accountName = account.name
9  val accountMask = account.mask
10  val accountSubType = account.subtype
11}
12val institutionId = metadata.institution?.id
13val institutionName = metadata.institution?.name

onExit

The onExit handler is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The PlaidError returned from the onExit handler is meant to help you guide your users after they have exited Link. We recommend storing the error and metadata information server-side in a way that can be associated with the user. You’ll also need to include this and any other relevant information in Plaid Support requests for the user.

onExit
error
Map<String, Object>
An object that contains the error type, error code, and error message of the error that was last encountered by the user. If no error was encountered, error will be null.
displayMessage
nullableString
A user-friendly representation of the error code. null if the error is not related to user action. This may change over time and is not safe for programmatic use.
errorCode
String
The particular error code. Each errorType has a specific set of errorCodes. A code of 499 indicates a client-side exception.
json
String
A string representation of the error code.
errorType
String
A broad categorization of the error.
errorMessage
String
A developer-friendly representation of the error code.
errorJson
nullableString
The data directly returned from the server with no client side changes.
LinkExitMetadata
Map<String, Object>
An object containing information about the exit event
linkSessionId
nullableString
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
institution
nullableobject
An institution object. If the Item was created via Same-Day micro-deposit verification, will be null.
name
string
The full institution name, such as 'Wells Fargo'
institution_id
string
The Plaid institution identifier
status
nullableString
The point at which the user exited the Link flow. One of the following values.
requires_questions
User prompted to answer security questions
requires_selections
User prompted to answer multiple choice question(s)
requires_recaptcha
User prompted to solve a reCAPTCHA challenge
requires_code
User prompted to provide a one-time passcode
choose_device
User prompted to select a device on which to receive a one-time passcode
requires_credentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution
requires_account_selection
User prompted to select one or more financial accounts to share
institution_not_found
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
unknown
An exit status that is not handled by the current version of the SDK
requestId
nullableString
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation
Select Language
1val exit = result as LinkExit
2
3val error = exit.error
4error?.let { err ->
5  val errorCode = err.errorCode
6  val errorMessage = err.errorMessage
7  val displayMessage = err.displayMessage
8}
9val metadata = exit.metadata
10val institutionId = metadata.institution?.id
11val institutionName = metadata.institution?.name
12val linkSessionId = metadata.linkSessionId;
13val requestId = metadata.requestId;

onEvent

The onEvent callback is called at certain points in the Link flow. Unlike the handlers for onSuccess and onExit, the onEvent handler is initialized as a global lambda passed to the Plaid class. OPEN events will be sent immediately upon Link’s opening, and remaining events will be sent by the time onSuccess or onExit is called. If you need the exact time when an event happened, use the timestamp property.
The following onEvent callbacks are stable, which means that they will not be deprecated or changed: OPEN, EXIT, HANDOFF, SELECT_INSTITUTION, ERROR, BANK_INCOME_INSIGHTS_COMPLETED, IDENTITY_VERIFICATION_PASS_SESSION, IDENTITY_VERIFICATION_FAIL_SESSION. The remaining callback events are informational and subject to change.

onEvent
eventName
String
A string representing the event that has just occurred in the Link flow.
BANK_INCOME_INSIGHTS_COMPLETED
The user has completed the Assets and Bank Income Insights flow.
CLOSE_OAUTH
The user closed the third-party website or mobile app without completing the OAuth flow.
ERROR
A recoverable error occurred in the Link flow, see the error_code metadata.
EXIT
The user has exited without completing the Link flow and the onExit callback is fired.
FAIL_OAUTH
The user encountered an error while completing the third-party's OAuth login flow.
HANDOFF
The user has exited Link after successfully linking an Item.
IDENTITY_VERIFICATION_START_STEP
The user has started a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_PASS_STEP
The user has passed a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_FAIL_STEP
The user has failed a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_PENDING_REVIEW_STEP
The user has reached the pending review state.
IDENTITY_VERIFICATION_CREATE_SESSION
The user has started a new Identity Verification session.
IDENTITY_VERIFICATION_RESUME_SESSION
The user has resumed an existing Identity Verification session.
IDENTITY_VERIFICATION_PASS_SESSION
The user has successfully completed their Identity Verification session.
IDENTITY_VERIFICATION_FAIL_SESSION
The user has failed their Identity Verification session.
IDENTITY_VERIFICATION_PENDING_REVIEW_SESSION
The user has completed their Identity Verification session, which is now in a pending review state.
IDENTITY_VERIFICATION_OPEN_UI
The user has opened the UI of their Identity Verification session.
IDENTITY_VERIFICATION_RESUME_UI
The user has resumed the UI of their Identity Verification session.
IDENTITY_VERIFICATION_CLOSE_UI
The user has closed the UI of their Identity Verification session.
MATCHED_SELECT_INSTITUTION
The user selected an institution that was presented as a matched institution. This event can be emitted either during the Returning User Experience flow or if the institution's routing_number was provided when calling /link/token/create. To distinguish between the two scenarios, see LinkEventMetadata.match_reason.
MATCHED_SELECT_VERIFY_METHOD
The user selected a verification method for a matched institution. This event is emitted only during the Returning User Experience flow.
OPEN
The user has opened Link.
OPEN_MY_PLAID
The user has opened my.plaid.com. This event is only emitted when Link is initialized with Assets as a product.
OPEN_OAUTH
The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.
SEARCH_INSTITUTION
The user has searched for an institution.
SELECT_BRAND
The user selected a brand, e.g. Bank of America. The SELECT_BRAND event is only emitted for large financial institutions with multiple online banking portals.
SELECT_DEGRADED_INSTITUTION
The user selected an institution with a DEGRADED health status and was shown a corresponding message.
SELECT_DOWN_INSTITUTION
The user selected an institution with a DOWN health status and was shown a corresponding message.
SELECT_INSTITUTION
The user selected an institution.
SUBMIT_ACCOUNT_NUMBER
The user has submitted an account number. This event emits the account_number_mask metadata to indicate the mask of the account number the user provided.
SUBMIT_CREDENTIALS
The user has submitted credentials.
SUBMIT_MFA
The user has submitted MFA.
SUBMIT_ROUTING_NUMBER
The user has submitted routing number. This event emits the routing_number metadata to indicate user's routing number.
TRANSITION_VIEW
The TRANSITION_VIEW event indicates that the user has moved from one view to the next.
UPLOAD_DOCUMENTS
The user is asked to upload documents (for Income verification).
VIEW_DATA_TYPES
The user has viewed data types on the data transparency consent pane.
UNKNOWN
The UNKNOWN event indicates that the event is not handled by the current version of the SDK.
LinkEventMetadata
Map<String, Object>
An object containing information about the event.
accountNumberMask
String
The account number mask extracted from the user-provided account number. If the user-inputted account number is four digits long, account_number_mask is empty. Emitted by SUBMIT_ACCOUNT_NUMBER.
errorCode
String
The error code that the user encountered. Emitted by: ERROR, EXIT.
errorMessage
String
The error message that the user encountered. Emitted by: ERROR, EXIT.
errorType
String
The error type that the user encountered. Emitted by: ERROR, EXIT.
exitStatus
String
The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT.
institutionId
String
The ID of the selected institution. Emitted by: all events.
institutionName
String
The name of the selected institution. Emitted by: all events.
institutionSearchQuery
String
The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.
isUpdateMode
String
Indicates if the current Link session is an update mode session. Emitted by: OPEN.
matchReason
nullablestring
The reason this institution was matched, which will be either returning_user or routing_number. Emitted by: MATCHED_SELECT_INSTITUTION.
routingNumber
Optional<String>
The routing number submitted by user at the micro-deposits routing number pane. Emitted by SUBMIT_ROUTING_NUMBER.
linkSessionId
String
The link_session_id is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: all events.
mfaType
String
If set, the user has encountered one of the following MFA types: code device questions selections. Emitted by: SUBMIT_MFA and TRANSITION_VIEW when view_name is MFA.
requestId
String
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
selection
String
Either the verification method for a matched institution selected by the user or the Auth Type Select flow type selected by the user. If selection is used to describe selected verification method, then possible values are phoneotp or password; if selection is used to describe the selected Auth Type Select flow, then possible values are flow_type_manual or flow_type_instant. Emitted by: MATCHED_SELECT_VERIFY_METHOD and SELECT_AUTH_TYPE.
timestamp
String
An ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z. Emitted by: all events.
viewName
String
The name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW.
ACCEPT_TOS
The view showing Terms of Service in the identity verification flow.
CONNECTED
The user has connected their account.
CONSENT
We ask the user to consent to the privacy policy.
CREDENTIAL
Asking the user for their account credentials.
DATA_TRANSPARENCY
We disclose the data types being shared.
DATA_TRANSPARENCY_CONSENT
We ask the user to consent to the privacy policy and disclose data types being shared.
DOCUMENTARY_VERIFICATION
The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor).
ERROR
An error has occurred.
EXIT
Confirming if the user wishes to close Link.
KYC_CHECK
The view representing the "know your customer" step in the identity verification flow.
LOADING
Link is making a request to our servers.
MATCHED_CONSENT
We ask the matched user to consent to the privacy policy and SMS terms.
MATCHED_CREDENTIAL
We ask the matched user for their account credentials to a matched institution.
MATCHED_MFA
We ask the matched user for MFA authentication to verify their identity.
MFA
The user is asked by the institution for additional MFA authentication.
NUMBERS
The user is asked to insert their account and routing numbers.
OAUTH
The user is informed they will authenticate with the financial institution via OAuth.
RECAPTCHA
The user was presented with a Google reCAPTCHA to verify they are human.
RISK_CHECK
The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor).
SCREENING
The watchlist screening step in the identity verification flow.
SELECT_ACCOUNT
We ask the user to choose an account.
SELECT_AUTH_TYPE
The user is asked to choose whether to Link instantly or manually (i.e., with micro-deposits).
SELECT_BRAND
The user is asked to select a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.
SELECT_INSTITUTION
We ask the user to choose their institution.
SELFIE_CHECK
The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.
UPLOAD_DOCUMENTS
The user is asked to upload documents (for Income verification).
VERIFY_SMS
The SMS verification step in the identity verification flow.
metadataJson
nullableString
The data directly returned from the server with no client side changes.
Select Language
1Plaid.setLinkEventListener { event -> Log.i("Event", event.toString()) }

Next steps

If you run into problems integrating with Plaid Link on Android, see Troubleshooting the Plaid Link Android SDK.

Once you've gotten Link working, see Link best practices for recommendations on further improving the Link flow.

api webhooks

Webhooks

API reference for webhooks

Prefer to learn by watching? Our video tutorial walks you through the basics of incorporating Plaid webhooks into your application.

Looking for webhook schemas? The reference documentation for specific webhooks (Transactions, Auth, Assets, Identity, Identity Verification, Monitor, Investments, Liabilities, Payment Initiation, Income, Virtual Accounts, Items, and Transfer) has moved to its respective API reference pages.

Introduction to webhooks

A webhook is an HTTP request used to provide push notifications. Plaid sends webhooks to programmatically inform you about changes to Plaid Items or the status of asynchronous processes. For example, Plaid will send a webhook when an Item is in an error state or has additional data available, or when a non-blocking process (like gathering transaction data or verifying a bank account via micro-deposits) is complete.

To receive Plaid webhooks, set up a dedicated endpoint on your server as a webhook listener that can receive POST requests, then provide this endpoint URL to Plaid as described in the next section. You can also test webhooks without setting up your own endpoint following the instructions in Testing webhooks in Sandbox.

Configuring webhooks

Webhooks are typically configured via the webhook parameter of /link/token/create, although some webhooks used in contexts where Link sessions are not required, such as Bank Transfer webhooks and Wallet transaction webhooks, are configured via the Plaid Dashboard instead. When specifying a webhook, the URL must be in the standard format of http(s)://(www.)domain.com/ and, if https, must have a valid SSL certificate.

To view response codes and debug any issues with webhook setup, see the Logs section in the Dashboard.

Plaid sends POST payloads with raw JSON to your webhook URL from one of the following IP addresses:

  • 52.21.26.131
  • 52.21.47.157
  • 52.41.247.19
  • 52.88.82.239

Note that these IP addresses are subject to change.

You can optionally verify webhooks to ensure they are from Plaid. For more information, see webhook verification.

Webhook retries

If there is a non-200 response or no response within 10 seconds from the webhook endpoint, Plaid will retry sending the webhook up to two times with a few minutes in between each webhook.

Best practices for applications using webhooks

You should design your application to handle duplicate, and out-of-order webhooks. Ensure idempotency on actions you take when receiving a webhook. If you drive application state with webhooks, ensure your code doesn't rely on a specific order of webhook receipt.

If you (or Plaid) experience downtime for longer than Plaid's retry period, you will lose webhooks. If you use webhooks for state transitions, ensure your application can self-heal by requesting Item state from Plaid's other endpoints if a webhook is not received within a window. All data present in webhooks is also present in our other APIs.

It's best to keep your receiver as simple as possible, such as a receiver whose only job is to write the webhook into a queue or reliable storage. This is important for two reasons. First, if the receiver does not respond within 10 seconds, the delivery is considered failed. Second, because webhooks can arrive at unpredictable rates. Therefore if you do a lot of work in your receiver - e.g. generating and sending an email - spikes are likely to overwhelm your downstream services, or cause you to be rate-limited if the downstream is a third-party.

Testing webhooks in Sandbox

Webhooks will fire as normal in the Sandbox environment. For testing purposes, you can also use the /sandbox/item/fire_webhook endpoint to fire a webhook on demand. If you don't have a webhook endpoint configured yet, you can also use a tool such as Request Bin to quickly and easily set up a webhook listener endpoint to provide to /sandbox/public_token/create. When directing webhook traffic to third-party tools, make sure you are using Plaid's Sandbox environment and not sending out live data.

Example in Plaid Pattern

For real-life examples of handling webhooks that illustrate how to handle sample transactions and Item webhooks, see handleTransactionsWebhook.js and handleItemWebhook.js These files contain webhook handling code for the Node-based Plaid Pattern sample app.

link react native android setup

Android Setup

Reference for setting up Android for use with the Link React Native SDK

Android Setup

Register your app id
  1. Log in to the Plaid dashboard and go to Team Settings -> API.
  2. Next to Allowed Android package names, click Configure, then Add New Android Package Name.
  3. Enter your package name, for example com.plaid.example.
  4. Click Save Changes. You may be prompted to re-enter your password.
Add PlaidPackage to your application
  1. Go to android/app/src/main/java/<AppName>/MainApplication.java and
  2. Add import com.plaid.PlaidPackage; to the imports section.
  3. Add packages.add(new PlaidPackage()); to List<ReactPackage> getPackages();.
Configure Gradle
  1. Go to the project level android/app/build.gradle.
  2. Make sure you are using a minsdkversion >= 21.
  3. Add the following dependencies:
1dependencies {
2    ...
3    implementation project(':react-native-plaid-link-sdk')
  1. Go to android/settings.gradle.
  2. Add the following lines:
1include ':react-native-plaid-link-sdk'
2project(':react-native-plaid-link-sdk').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-plaid-link-sdk/android')

Now your React Native application is linked to the Plaid React Native SDK for Android development. Next Open Link.

support

Plaid help and support

Get help for your Plaid integration

Consumer support

If you are using Plaid to connect your financial accounts and have questions, use the links below for more information:

To learn more about Plaid and how it works, see our page on How Plaid Works.

If you are having trouble linking your financial institution, see our Connecting Financial Accounts Guide on the Plaid Help Center for more information. If you have questions about linking through a specific Plaid-powered app, we recommend reaching out to the app directly for assistance.

Developer support

If you are a developer building with Plaid, the answers to most questions can be found in the docs -- try using the search feature, or try "Ask Finn" within the search menu to ask our friendly chatbot for help!

Troubleshooting details for specific errors or failed requests can be found in the Dashboard:

If you do not have a Dashboard account, you can ask the team member who manages your Plaid team to invite you to the team.

If you can't find an answer to your question in the docs or Dashboard, file a Support ticket via your Dashboard account.

For general questions about using Plaid APIs, or help getting started with your integration, you can also ask the Plaid community on Stack Overflow.

Core Exchange and Plaid Exchange documentation and support

If you are a developer at a bank or other financial institution looking for information about APIs used to provide consumer-permissioned data to Plaid, help and documentation for the Core Exchange and Plaid Exchange APIs can be found on their dedicated sites:

Prospective customer support

If you have a question about Plaid capabilities that isn't answered in the docs, or for details about pricing, contact Sales to learn more.

No code support

If you're looking for a third party who can build a Plaid integration for you, rather than building one yourself, fill out the Developer Partner Resource request form and we can help you find a Plaid integrator to meet your needs.

transactions add to app

Add Transactions to your app

Learn how to fetch Transactions data for your users

Try out the Pattern Demo for a demonstration of a sample app that uses Plaid's Transactions product for the personal financial management use case.

In this guide, we'll start from scratch and walk through how to use Transactions to perform an initial fetch of a user's transaction history. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, you can skip ahead to Fetching transaction data.

Prefer to learn by watching? A video tutorial is available for this topic.

Get Plaid API keys and complete application and company profile

If you don't already have one, you'll need to create a Plaid developer account. After creating your account, you can find your API keys under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your application profile and company profile on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the Plaid Portal. Your application profile and company profile must be completed before connecting to certain institutions in Production.

Install and initialize Plaid libraries

You can use our official server-side client libraries to connect to the Plaid API from your application:

Select group for content switcher
Select Language
1// Install via npm
2npm install --save plaid

After you've installed Plaid's client libraries, you can initialize them by passing in your client_id, secret, and the environment you wish to connect to (Sandbox, Development, or Production). This will make sure the client libraries pass along your client_id and secret with each request, and you won't need to explicitly include them in any other calls.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can obtain from the Dashboard. These code samples also demonstrate starting up a server commonly used in each framework (such as Express or Flask).

Select group for content switcher
Select Language
1// Using Express
2const express = require('express');
3const app = express();
4app.use(express.json());
5
6const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
7
8const configuration = new Configuration({
9  basePath: PlaidEnvironments.sandbox,
10  baseOptions: {
11    headers: {
12      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
13      'PLAID-SECRET': process.env.PLAID_SECRET,
14    },
15  },
16});
17
18const client = new PlaidApi(configuration);

Create an Item with Link

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the Link documentation.

Using Link, we will create a Plaid Item, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. If you want to customize Link's look and feel, you can do so from the Dashboard.

Before initializing Link, you will need to create a new link_token on the server side of your application. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the /link/token/create endpoint. Then, on the client side of your application, you'll need to initialize Link with the link_token that you just created.

Create a link_token
Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['transactions'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Install Link dependency
Select Language
1<head>
2  <title>Connect a bank</title>
3  <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
4</head>
Configure the client-side Link handler
1const linkHandler = Plaid.create({
2  token: (await $.post('/create_link_token)).link_token,
3  onSuccess: (public_token, metadata) => {
4    // Send the public_token to your app server.
5    $.post('/exchange_public_token', {
6      public_token: public_token,
7    });
8  },
9  onExit: (err, metadata) => {
10    // Optionally capture when your user exited the Link flow.
11    // Storing this information can be helpful for support.
12  },
13  onEvent: (eventName, metadata) => {
14    // Optionally capture Link flow events, streamed through
15    // this callback as your users connect an Item to Plaid.
16  },
17});
18
19linkHandler.open();

Get a persistent access token

Next, on the server side, we need to exchange our public_token for an access_token and item_id. The access_token will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the /item/public_token/exchange endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the access_token and item_id in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. The access_token will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via /item/remove. The access_token should be stored securely, and never in client-side code. A public_token is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

Select group for content switcher
Select Language
1app.post('/api/exchange_public_token', async function (
2  request,
3  response,
4  next,
5) {
6  const publicToken = request.body.public_token;
7  try {
8    const response = await client.itemPublicTokenExchange({
9      public_token: publicToken,
10    });
11
12    // These values should be saved to a persistent database and
13    // associated with the currently signed-in user
14    const accessToken = response.data.access_token;
15    const itemID = response.data.item_id;
16
17    res.json({ public_token_exchange: 'complete' });
18  } catch (error) {
19    // handle error
20  }
21});

Fetching transaction data

Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API and fetch transaction data using the /transactions/sync endpoint.

The /transactions/sync endpoint is used to both initialize your view of transactions data, and keep you current with any changes that have occurred. When you first call it on an Item with no cursor parameter, transactions data available at that time is returned. If more updates are available than requested with the count parameter (maximum of 500), has_more will be set to true, indicating the endpoint should be called again, using the next_cursor from the previous response in the cursor field of the next request, to receive another page of data. After successfully pulling all currently available pages, you can store the cursor for later requests, allowing Plaid to send you new updates from when you last queried the endpoint.

Note that if you encounter an error during pagination, it's important to restart the pagination loop from the beginning. For more details, see the documentation for TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION. For sample code for handling the error, see the /transactions/sync API reference.

Typically, the first 30 days of transaction history is available to be fetched almost immediately, but full transaction history may take a minute or more to become available. If you get an empty response when calling /transactions/sync shortly after linking an Item, it's likely that the first 30 days of transaction history has not yet been pulled. You will need to call the endpoint when the data is pulled. Similarly, if you only get the first 30 days of transaction history, you will need to wait until it is complete, and call the endpoint again.

To be notified whenever additional data becomes available, see Transaction webhooks.

Select Language
1// Provide a cursor from your database if you've previously
2// received one for the Item. Leave null if this is your
3// first sync call for this Item. The first request will
4// return a cursor.
5let cursor = database.getLatestCursorOrNull(itemId);
6
7// New transaction updates since "cursor"
8let added: Array<Transaction> = [];
9let modified: Array<Transaction> = [];
10// Removed transaction ids
11let removed: Array<RemovedTransaction> = [];
12let hasMore = true;
13
14// Iterate through each page of new transaction updates for item
15while (hasMore) {
16  const request: TransactionsSyncRequest = {
17    access_token: accessToken,
18    cursor: cursor,
19  };
20  const response = await client.transactionsSync(request);
21  const data = response.data;
22
23  // Add this page of results
24  added = added.concat(data.added);
25  modified = modified.concat(data.modified);
26  removed = removed.concat(data.removed);
27
28  hasMore = data.has_more;
29
30  // Update cursor to the next cursor
31  cursor = data.next_cursor;
32}
33
34// Persist cursor and updated data
35database.applyUpdates(itemId, added, modified, removed, cursor);

Updating transaction data

After your initial /transactions/sync request, you may want your application to be notified when any transactions are added, removed, or modified in order to immediately fetch them from /transactions/sync. To learn how, see Transaction Webhooks.

Example code in Plaid Pattern

For a real-life example of an app that incorporates transactions, see the Node-based Plaid Pattern sample app. Pattern is a sample financial management app that fetches transactions data upon receipt of transactions webhooks. Transactions code in Plaid Pattern can be found in handleTransactionsWebhook.js.

Fetching by date

If you want to fetch transactions data by date range, you can use the /transactions/get endpoint.

Next steps

If you're ready to launch to Production, see the Launch checklist.

errors sandbox

Sandbox Errors

Guide to troubleshooting Sandbox errors

SANDBOX_PRODUCT_NOT_ENABLED

The requested product is not enabled for an Item
Common causes
  • A sandbox operation could not be performed because a product has not been enabled on the Sandbox Item.
Troubleshooting steps

If the error persists, submit a Support ticket.

1http code 400
2{
3 "error_type": "SANDBOX_ERROR",
4 "error_code": "SANDBOX_PRODUCT_NOT_ENABLED",
5 "error_message": "The [auth | transactions | ...] product is not enabled on this item",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

SANDBOX_WEBHOOK_INVALID

The request to fire a Sandbox webhook failed.
Common causes
Troubleshooting steps
1http code 400
2{
3 "error_type": "SANDBOX_ERROR",
4 "error_code": "SANDBOX_WEBHOOK_INVALID",
5 "error_message": "Webhook for this item is either not set up, or invalid. Please update the item's webhook and try again.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

SANDBOX_ACCOUNT_SELECT_V2_NOT_ENABLED

The item was not created with Account Select v2
Common causes
  • A Sandbox operation could not be performed because the the Sandbox Item was not created with Account Select v2.
Troubleshooting steps
1http code 400
2{
3 "error_type": "SANDBOX_ERROR",
4 "error_code": "SANDBOX_ACCOUNT_SELECT_V2_NOT_ENABLED",
5 "error_message": "The item was not created with Account Select v2",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

SANDBOX_TRANSFER_EVENT_TRANSITION_INVALID

The /sandbox/transfer/simulate endpoint was called with parameters specifying an invalid event transition.
Common causes
Troubleshooting steps
1http code 400
2{
3 "error_type": "SANDBOX_ERROR",
4 "error_code": "SANDBOX_TRANSFER_EVENT_TRANSITION_INVALID",
5 "error_message": "The provided simulated event type is incompatible with the current transfer status",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

api products identity

Identity

API reference for Identity endpoints and webhooks

Verify the name, address, phone number, and email address of a user against bank account information on file.

Endpoints
/identity/getFetch identity data
/identity/matchMatch client identity with bank identity

Endpoints

/identity/get

Retrieve identity data

The /identity/get endpoint allows you to retrieve various account holder information on file with the financial institution, including names, emails, phone numbers, and addresses. Only name data is guaranteed to be returned; other fields will be empty arrays if not provided by the institution.
This request may take some time to complete if identity was not specified as an initial product when creating the Item. This is because Plaid must communicate directly with the institution to retrieve the data.
Note: In API versions 2018-05-22 and earlier, the owners object is not returned, and instead identity information is returned in the top level identity object. For more details, see Plaid API versioning.

identity/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
options
object
An optional object to filter /identity/get results.
account_ids
[string]
A list of account_ids to retrieve for the Item. Note: An error will be returned if a provided account_id is not associated with the Item.
Select group for content switcher
Select Language
1// Pull Identity data for an Item
2const request: IdentityGetRequest = {
3  access_token: accessToken,
4};
5try {
6  const response = await plaidClient.identityGet(request);
7  const identities = response.data.accounts.flatMap(
8    (account) => account.owners,
9  );
10} catch (error) {
11  // handle error
12}
identity/get

Response fields and example

accounts
[object]
The accounts for which Identity data has been requested
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullablenumber
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullablenumber
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullablenumber
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullablestring
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
owners
[object]
Data returned by the financial institution about the account owner or owners. Only returned by Identity or Assets endpoints. For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution. Multiple owners on a single account will be represented in the same owner object, not in multiple owner objects within the array. In API versions 2018-05-22 and earlier, the owners object is not returned, and instead identity information is returned in the top level identity object. For more details, see Plaid API versioning
names
[string]
A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders.
If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.
phone_numbers
[object]
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
string
The phone number.
primary
boolean
When true, identifies the phone number as the primary number on an account.
type
string
The type of phone number.

Possible values: home, work, office, mobile, mobile1, other
emails
[object]
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
string
The email address.
primary
boolean
When true, identifies the email address as the primary email on an account.
type
string
The type of email account as described by the financial institution.

Possible values: primary, secondary, other
addresses
[object]
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
object
Data about the components comprising an address.
city
nullablestring
The full city name
region
nullablestring
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
nullablestring
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code
primary
boolean
When true, identifies the address as the primary address on an account.
item
object
Metadata about the Item.
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
nullablestring
The Plaid Institution ID associated with the Item. Field is null for Items created via Same Day Micro-deposits.
webhook
nullablestring
The URL registered to receive webhooks for the Item.
error
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
available_products
[string]
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
billed_products
[string]
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available_products. Note - billed_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
products
[string]
A list of initialized products for the Item. In almost all cases, this will be the same as the billed_products field. For some products, it is possible for the product to be initialized on an Item but not yet billed (e.g. Assets, before /asset_report/create has been called), in which case the product may appear in products but not in billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consented_products
[string]
A list of products that have gone through consent collection for the Item. Only present for those enabled in the Data Transparency beta. If you are not enrolled in Data Transparency, this field is not used.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consent_expiration_time
nullablestring
The RFC 3339 timestamp after which the consent provided by the end user will expire. Upon consent expiration, the item will enter the ITEM_LOGIN_REQUIRED error state. To circumvent the ITEM_LOGIN_REQUIRED error and maintain continuous consent, the end user can reauthenticate via Link’s update mode in advance of the consent expiration time.
Note - This is only relevant for certain OAuth-based institutions. For all other institutions, this field will be null.

Format: date-time
update_type
string
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication.
background - Item can be updated in the background
user_present_required - Item requires user interaction to be updated

Possible values: background, user_present_required
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "accounts": [
3    {
4      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
5      "balances": {
6        "available": 100,
7        "current": 110,
8        "iso_currency_code": "USD",
9        "limit": null,
10        "unofficial_currency_code": null
11      },
12      "mask": "0000",
13      "name": "Plaid Checking",
14      "official_name": "Plaid Gold Standard 0% Interest Checking",
15      "owners": [
16        {
17          "addresses": [
18            {
19              "data": {
20                "city": "Malakoff",
21                "country": "US",
22                "postal_code": "14236",
23                "region": "NY",
24                "street": "2992 Cameron Road"
25              },
26              "primary": true
27            },
28            {
29              "data": {
30                "city": "San Matias",
31                "country": "US",
32                "postal_code": "93405-2255",
33                "region": "CA",
34                "street": "2493 Leisure Lane"
35              },
36              "primary": false
37            }
38          ],
39          "emails": [
40            {
41              "data": "accountholder0@example.com",
42              "primary": true,
43              "type": "primary"
44            },
45            {
46              "data": "accountholder1@example.com",
47              "primary": false,
48              "type": "secondary"
49            },
50            {
51              "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
52              "primary": false,
53              "type": "other"
54            }
55          ],
56          "names": [
57            "Alberta Bobbeth Charleson"
58          ],
59          "phone_numbers": [
60            {
61              "data": "1112223333",
62              "primary": false,
63              "type": "home"
64            },
65            {
66              "data": "1112224444",
67              "primary": false,
68              "type": "work"
69            },
70            {
71              "data": "1112225555",
72              "primary": false,
73              "type": "mobile"
74            }
75          ]
76        }
77      ],
78      "subtype": "checking",
79      "type": "depository"
80    },
81    {
82      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
83      "balances": {
84        "available": 200,
85        "current": 210,
86        "iso_currency_code": "USD",
87        "limit": null,
88        "unofficial_currency_code": null
89      },
90      "mask": "1111",
91      "name": "Plaid Saving",
92      "official_name": "Plaid Silver Standard 0.1% Interest Saving",
93      "owners": [
94        {
95          "addresses": [
96            {
97              "data": {
98                "city": "Malakoff",
99                "country": "US",
100                "postal_code": "14236",
101                "region": "NY",
102                "street": "2992 Cameron Road"
103              },
104              "primary": true
105            },
106            {
107              "data": {
108                "city": "San Matias",
109                "country": "US",
110                "postal_code": "93405-2255",
111                "region": "CA",
112                "street": "2493 Leisure Lane"
113              },
114              "primary": false
115            }
116          ],
117          "emails": [
118            {
119              "data": "accountholder0@example.com",
120              "primary": true,
121              "type": "primary"
122            },
123            {
124              "data": "accountholder1@example.com",
125              "primary": false,
126              "type": "secondary"
127            },
128            {
129              "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
130              "primary": false,
131              "type": "other"
132            }
133          ],
134          "names": [
135            "Alberta Bobbeth Charleson"
136          ],
137          "phone_numbers": [
138            {
139              "data": "1112223333",
140              "primary": false,
141              "type": "home"
142            },
143            {
144              "data": "1112224444",
145              "primary": false,
146              "type": "work"
147            },
148            {
149              "data": "1112225555",
150              "primary": false,
151              "type": "mobile"
152            }
153          ]
154        }
155      ],
156      "subtype": "savings",
157      "type": "depository"
158    }
159  ],
160  "item": {
161    "available_products": [
162      "balance",
163      "investments"
164    ],
165    "billed_products": [
166      "assets",
167      "auth",
168      "identity",
169      "liabilities",
170      "transactions"
171    ],
172    "consent_expiration_time": null,
173    "error": null,
174    "institution_id": "ins_3",
175    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
176    "update_type": "background",
177    "webhook": "https://www.genericwebhookurl.com/webhook"
178  },
179  "request_id": "3nARps6TOYtbACO"
180}
Was this helpful?

/identity/match

This feature is in currently in beta; please reach out to your Plaid Account Manager if you would like it enabled.

Retrieve identity match score

The /identity/match endpoint generates a match score, which indicates how well the provided identity data matches the identity information on file with the account holder's financial institution.
This request may take some time to complete if Identity was not specified as an initial product when creating the Item. This is because Plaid must communicate directly with the institution to retrieve the data.

identity/match

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
user
object
The user's legal name, phone number, email address and address used to perform fuzzy match. If Financial Account Matching is enabled in the Identity Verification product, leave this field empty to automatically match against PII collected from the Identity Verification checks.
legal_name
string
The user's full legal name.
phone_number
string
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis.
email_address
string
The user's email address.
address
object
Data about the components comprising an address.
city
string
The full city name
region
string
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
string
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
string
The ISO 3166-1 alpha-2 country code
options
object
An optional object to filter /identity/match results
account_ids
[string]
An array of account_ids to perform fuzzy match
Select Language
1// Match identity provided by client against bank/account identity
2const request: IdentityMatchRequest = {
3  access_token: accessToken,
4};
5try {
6  const response = await plaidClient.identityMatch(request);
7  const accounts = response.data.accounts
8  for(var account of accounts) {
9        const legalNameScore = account.legal_name
10        const phoneScore = account.phone_number
11        const emailScore = account.email_address
12        const addressScore = account.address
13        if (legalNameScore != null) {
14          const legalNameScoreValue = legalNameScore.score
15        }
16    }
17} catch (error) {
18  // handle error
19}
identity/match

Response fields and example

accounts
[object]
The accounts for which Identity match has been requested
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullablenumber
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullablenumber
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullablenumber
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullablestring
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
legal_name
nullableobject
Score found by matching name provided by the API with the name on the account at the financial institution. If the account contains multiple owners, the maximum match score is filled.
score
nullableinteger
Match score for name. 100 is a perfect score, 99-85 means a strong match, 84-70 is a partial match, any score less than 70 is a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the name is missing from either the API or financial institution, this is null.
is_first_name_or_last_name_match
nullableboolean
first or last name completely matched, likely a family member
is_nickname_match
nullableboolean
nickname matched, example Jennifer and Jenn.
is_business_name_detected
deprecatednullableboolean
Is true if the name on either of the names that was matched for the score contained strings indicative of a business name, such as "CORP", "LLC", "INC", or "LTD". A true result generally indicates the entity is a business. However, a false result does not mean the entity is not a business, as some businesses do not use these strings in the names used for their financial institution accounts.
phone_number
nullableobject
Score found by matching phone number provided by the API with the phone number on the account at the financial institution. 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled.
score
nullableinteger
Match score for normalized phone number. 100 is a perfect match, 99-70 is a partial match (matching the same phone number with extension against one without extension etc.), anything below 70 is considered a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the phone number is missing from either the API or financial institution, this is null.
email_address
nullableobject
Score found by matching email provided by the API with the email on the account at the financial institution. 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled.
score
nullableinteger
Match score for normalized email. 100 is a perfect match, 99-70 is a partial match (matching the same email with different '+' extensions), anything below 70 is considered a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the email is missing from either the API or financial institution, this is null.
address
nullableobject
Score found by matching address provided by the API with the address on the account at the financial institution. The score can range from 0 to 100 where 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled.
score
nullableinteger
Match score for address. 100 is a perfect match, 99-90 is a strong match, 89-80 is a partial match, anything below 80 is considered a weak match. Typically, the match threshold should be set to a score of 80 or higher. If the address is missing from either the API or financial institution, this is null.
is_postal_code_match
nullableboolean
postal code was provided for both and was a match
item
object
Metadata about the Item.
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
nullablestring
The Plaid Institution ID associated with the Item. Field is null for Items created via Same Day Micro-deposits.
webhook
nullablestring
The URL registered to receive webhooks for the Item.
error
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
available_products
[string]
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
billed_products
[string]
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available_products. Note - billed_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
products
[string]
A list of initialized products for the Item. In almost all cases, this will be the same as the billed_products field. For some products, it is possible for the product to be initialized on an Item but not yet billed (e.g. Assets, before /asset_report/create has been called), in which case the product may appear in products but not in billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consented_products
[string]
A list of products that have gone through consent collection for the Item. Only present for those enabled in the Data Transparency beta. If you are not enrolled in Data Transparency, this field is not used.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consent_expiration_time
nullablestring
The RFC 3339 timestamp after which the consent provided by the end user will expire. Upon consent expiration, the item will enter the ITEM_LOGIN_REQUIRED error state. To circumvent the ITEM_LOGIN_REQUIRED error and maintain continuous consent, the end user can reauthenticate via Link’s update mode in advance of the consent expiration time.
Note - This is only relevant for certain OAuth-based institutions. For all other institutions, this field will be null.

Format: date-time
update_type
string
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication.
background - Item can be updated in the background
user_present_required - Item requires user interaction to be updated

Possible values: background, user_present_required
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "accounts": [
3    {
4      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
5      "balances": {
6        "available": 100,
7        "current": 110,
8        "iso_currency_code": "USD",
9        "limit": null,
10        "unofficial_currency_code": null
11      },
12      "mask": "0000",
13      "name": "Plaid Checking",
14      "official_name": "Plaid Gold Standard 0% Interest Checking",
15      "legal_name": {
16        "score": 90,
17        "is_nickname_match": true,
18        "is_first_name_or_last_name_match": true,
19        "is_business_name_detected": false
20      },
21      "phone_number": {
22        "score": 100
23      },
24      "email_address": {
25        "score": 100
26      },
27      "address": {
28        "score": 100,
29        "is_postal_code_match": true
30      },
31      "subtype": "checking",
32      "type": "depository"
33    },
34    {
35      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
36      "balances": {
37        "available": 200,
38        "current": 210,
39        "iso_currency_code": "USD",
40        "limit": null,
41        "unofficial_currency_code": null
42      },
43      "mask": "1111",
44      "name": "Plaid Saving",
45      "official_name": "Plaid Silver Standard 0.1% Interest Saving",
46      "legal_name": {
47        "score": 30,
48        "is_first_name_or_last_name_match": false
49      },
50      "phone_number": {
51        "score": 100
52      },
53      "email_address": null,
54      "address": {
55        "score": 100,
56        "is_postal_code_match": true
57      },
58      "subtype": "savings",
59      "type": "depository"
60    }
61  ],
62  "item": {
63    "available_products": [
64      "balance",
65      "investments"
66    ],
67    "billed_products": [
68      "assets",
69      "auth",
70      "identity",
71      "liabilities",
72      "transactions"
73    ],
74    "consent_expiration_time": null,
75    "error": null,
76    "institution_id": "ins_3",
77    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
78    "update_type": "background",
79    "webhook": "https://www.genericwebhookurl.com/webhook"
80  },
81  "request_id": "3nARps6TOYtbACO"
82}
Was this helpful?

Webhooks (beta)

This feature is in currently in beta; please reach out to your Plaid Account Manager if you would like it enabled.

DEFAULT_UPDATE

Fired when a change to identity data has been detected on an Item. Items are checked for identity updates every 30-90 days. We recommend that upon receiving this webhook you make another call to /identity/get to fetch the user's latest identity data.

webhook_type
string
IDENTITY
webhook_code
string
DEFAULT_UPDATE
item_id
string
The item_id of the Item associated with this webhook, warning, or error
account_ids_with_updated_identity
object
An object with keys of account_id's that are mapped to their respective identity attributes that changed.
Example: { "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58": ["PHONES"] }
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "IDENTITY",
3  "webhook_code": "DEFAULT_UPDATE",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "account_ids_with_updated_identity": {
6    "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp": [
7      "ADDRESSES"
8    ]
9  },
10  "error": null,
11  "environment": "production"
12}
Was this helpful?

link best practices

Optimizing Link conversion

Discover best practices for improving Link conversion

Prefer to learn by watching? A video guide is available for this topic.

Overview

This guide contains tips for optimizing your existing Link implementation to help increase conversion and improve your users’ experiences with Link. If you are new to Link or don’t yet have a working Link integration, see Link overview for instructions on getting started with Link.

Measuring Link conversion

To evaluate the impact of changes to your integration, it's a good idea to implement conversion tracking before attempting to optimize conversion. For details, see Tracking Link conversion.

Improving Link conversion

Many different steps can be taken to maximize Link conversion, and the exact impact of these steps will vary for each customer and use case. The recommendations below are provided in general priority order.

Initialize with a minimal set of products

In general, calling /link/token/create with a minimal set of products will both increase conversion and reduce your costs. For more details, see Choosing when to initialize products.

Implement RUX support

The returning user experience (RUX) allows customers at some banks who have used Plaid before to have a streamlined experience when using the Link flow. If you collect phone number data for your users and have it available when they enter the Link flow, implementing RUX will increase conversion for eligible users. For more details, see Returning user experience.

Implement full OAuth support on mobile, including app-to-app

While supporting mobile app-to-app impacts only a small number of banks (currently only Chase), the impact on conversion for eligible users is very large, as app-to-app flows can allow users to authenticate with biometrics instead of a username and password. For iOS, supporting app-to-app requires creating an apple-app-site-association file to support universal links. On Android, supporting app-to-app requires registering your Android package name. For more details, see the OAuth Guide.

Provide pre-Link messaging

Link conversion is highest when users have the right expectations set going into Link. Your app should explain why you use Plaid, the benefits for the user of connecting their account, and that the user's information will be secure. It should also set the user's expectations around what information they will need to provide during the Link flow. Plaid should be configured as the default experience. For more details, including visual examples, see Pre-Link messaging for optimizing conversion.

(For Auth customers) Implement micro-deposit based Auth

While the vast majority of users can use Plaid's default Auth flows, some users, especially those at smaller banks and credit unions, have accounts that do not support those flows. Implementing micro-deposit-based Auth flows will increase conversion by allowing these users to link their accounts. For more details, see Auth coverage.

Configure Link for your user's country and language

For apps with multi-language experiences, custom profiles improve conversion by allowing you to display Link in your user's preferred language. Calling /link/token/create with the country parameter set to your user's specific country, rather than all countries your app supports, will allow Link to show a more accurately targeted list of institutions. For Auth customers, calling /link/token/create with country set to just US is also required to enable the conversion-maximizing Instant Match and micro-deposit based Auth flows.

Customize Link with your organization's branding

Plaid allows you to customize certain aspects of the Link UI. Customizing these in a way that matches your app -- for example, uploading your organizations's logo to be used on the Link consent pane or matching your brand colors can increase conversion. For more details, see Customizing Link.

(If applicable) Use the Institution Select shortcut

If you already know the institution your user plans to connect before the Link flow is launched, you can highlight this institution in the Institution Select UI by specifying the routing number during the /link/token/create call. For more details, see Institution Select shortcut.

api products virtual accounts

Virtual Accounts (UK and Europe)

API reference for Virtual Accounts endpoints and webhooks

Manage the entire lifecycle of a payment.

Virtual account functionality is currently supported only in Sandbox and Production.

Endpoints
/wallet/createCreate a virtual account
/wallet/getFetch a virtual account
/wallet/listList all virtual accounts
/wallet/transaction/executeExecute a transaction
/wallet/transaction/getFetch a transaction
/wallet/transaction/listList all transactions
See also
/payment_initiation/payment/reverseRefund a payment from a virtual account
Webhooks
WALLET_TRANSACTION_STATUS_UPDATEThe status of a transaction has changed

Endpoints

/wallet/create

Create an e-wallet

Create an e-wallet. The response is the newly created e-wallet object.

wallet/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
iso_currency_code
requiredstring
An ISO-4217 currency code, used with e-wallets and transactions.

Possible values: GBP, EUR
Min length: 3
Max length: 3
Select Language
1const request: WalletCreateRequest = {
2  iso_currency_code: isoCurrencyCode,
3};
4try {
5  const response = await plaidClient.walletCreate(request);
6  const walletID = response.data.wallet_id;
7  const balance = response.data.balance;
8  const numbers = response.data.numbers;
9  const recipientID = response.data.recipient_id;
10} catch (error) {
11  // handle error
12}
wallet/create

Response fields and example

wallet_id
string
A unique ID identifying the e-wallet
balance
object
An object representing the e-wallet balance
iso_currency_code
string
The ISO-4217 currency code of the balance
current
number
The total amount of funds in the account

Format: double
numbers
object
An object representing the e-wallet account numbers
bacs
nullableobject
An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
international
nullableobject
Account numbers using the International Bank Account Number and BIC/SWIFT code format.
iban
string
International Bank Account Number (IBAN).

Min length: 15
Max length: 34
bic
string
The Business Identifier Code, also known as SWIFT code, for this bank account.

Min length: 8
Max length: 11
recipient_id
string
The ID of the recipient that corresponds to the e-wallet account numbers
status
string
The status of the wallet.
UNKNOWN: The wallet status is unknown.
ACTIVE: The wallet is active and ready to send money to and receive money from.
CLOSED: The wallet is closed. Any transactions made to or from this wallet will error.

Possible values: UNKNOWN, ACTIVE, CLOSED
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
3  "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f6",
4  "balance": {
5    "iso_currency_code": "GBP",
6    "current": 123.12
7  },
8  "request_id": "4zlKapIkTm8p5KM",
9  "numbers": {
10    "bacs": {
11      "account": "12345678",
12      "sort_code": "123456"
13    }
14  },
15  "status": "ACTIVE"
16}
Was this helpful?

/wallet/get

Fetch an e-wallet

Fetch an e-wallet. The response includes the current balance.

wallet/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
wallet_id
requiredstring
The ID of the e-wallet

Min length: 1
Select Language
1const request: WalletGetRequest = {
2  wallet_id: walletID,
3};
4try {
5  const response = await plaidClient.walletGet(request);
6  const walletID = response.data.wallet_id;
7  const balance = response.data.balance;
8  const numbers = response.data.numbers;
9  const recipientID = response.data.recipient_id;
10} catch (error) {
11  // handle error
12}
wallet/get

Response fields and example

wallet_id
string
A unique ID identifying the e-wallet
balance
object
An object representing the e-wallet balance
iso_currency_code
string
The ISO-4217 currency code of the balance
current
number
The total amount of funds in the account

Format: double
numbers
object
An object representing the e-wallet account numbers
bacs
nullableobject
An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
international
nullableobject
Account numbers using the International Bank Account Number and BIC/SWIFT code format.
iban
string
International Bank Account Number (IBAN).

Min length: 15
Max length: 34
bic
string
The Business Identifier Code, also known as SWIFT code, for this bank account.

Min length: 8
Max length: 11
recipient_id
string
The ID of the recipient that corresponds to the e-wallet account numbers
status
string
The status of the wallet.
UNKNOWN: The wallet status is unknown.
ACTIVE: The wallet is active and ready to send money to and receive money from.
CLOSED: The wallet is closed. Any transactions made to or from this wallet will error.

Possible values: UNKNOWN, ACTIVE, CLOSED
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
3  "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f6",
4  "balance": {
5    "iso_currency_code": "GBP",
6    "current": 123.12
7  },
8  "request_id": "4zlKapIkTm8p5KM",
9  "numbers": {
10    "bacs": {
11      "account": "12345678",
12      "sort_code": "123456"
13    },
14    "international": {
15      "iban": "GB33BUKB20201555555555",
16      "bic": "BUKBGB22"
17    }
18  },
19  "status": "ACTIVE"
20}
Was this helpful?

/wallet/list

Fetch a list of e-wallets

This endpoint lists all e-wallets in descending order of creation.

wallet/list

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
iso_currency_code
string
An ISO-4217 currency code, used with e-wallets and transactions.

Possible values: GBP, EUR
Min length: 3
Max length: 3
cursor
string
A base64 value representing the latest e-wallet that has already been requested. Set this to next_cursor received from the previous /wallet/list request. If provided, the response will only contain e-wallets created before that e-wallet. If omitted, the response will contain e-wallets starting from the most recent, and in descending order.

Max length: 256
count
integer
The number of e-wallets to fetch

Minimum: 1
Maximum: 20
Default: 10
Select Language
1const request: WalletListRequest = {
2  iso_currency_code: 'GBP',
3  count: 10,
4};
5try {
6  const response = await plaidClient.walletList(request);
7  const wallets = response.data.wallets;
8  const nextCursor = response.data.next_cursor;
9} catch (error) {
10  // handle error
11}
wallet/list

Response fields and example

wallets
[object]
An array of e-wallets
wallet_id
string
A unique ID identifying the e-wallet
balance
object
An object representing the e-wallet balance
iso_currency_code
string
The ISO-4217 currency code of the balance
current
number
The total amount of funds in the account

Format: double
numbers
object
An object representing the e-wallet account numbers
bacs
nullableobject
An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
international
nullableobject
Account numbers using the International Bank Account Number and BIC/SWIFT code format.
iban
string
International Bank Account Number (IBAN).

Min length: 15
Max length: 34
bic
string
The Business Identifier Code, also known as SWIFT code, for this bank account.

Min length: 8
Max length: 11
recipient_id
string
The ID of the recipient that corresponds to the e-wallet account numbers
status
string
The status of the wallet.
UNKNOWN: The wallet status is unknown.
ACTIVE: The wallet is active and ready to send money to and receive money from.
CLOSED: The wallet is closed. Any transactions made to or from this wallet will error.

Possible values: UNKNOWN, ACTIVE, CLOSED
next_cursor
string
Cursor used for fetching e-wallets created before the latest e-wallet provided in this response
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "wallets": [
3    {
4      "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
5      "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f6",
6      "balance": {
7        "iso_currency_code": "GBP",
8        "current": 123.12
9      },
10      "numbers": {
11        "bacs": {
12          "account": "12345678",
13          "sort_code": "123456"
14        }
15      },
16      "status": "ACTIVE"
17    },
18    {
19      "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a999",
20      "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f7",
21      "balance": {
22        "iso_currency_code": "EUR",
23        "current": 456.78
24      },
25      "numbers": {
26        "international": {
27          "iban": "GB22HBUK40221241555626",
28          "bic": "HBUKGB4B"
29        }
30      },
31      "status": "ACTIVE"
32    }
33  ],
34  "request_id": "4zlKapIkTm8p5KM"
35}
Was this helpful?

/wallet/transaction/execute

Execute a transaction using an e-wallet

Execute a transaction using the specified e-wallet. Specify the e-wallet to debit from, the counterparty to credit to, the idempotency key to prevent duplicate transactions, the amount and reference for the transaction. Transactions will settle in seconds to several days, depending on the underlying payment rail.

wallet/transaction/execute

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
idempotency_key
requiredstring
A random key provided by the client, per unique wallet transaction. Maximum of 128 characters.
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. If a request to execute a wallet transaction fails due to a network connection error, then after a minimum delay of one minute, you can retry the request with the same idempotency key to guarantee that only a single wallet transaction is created. If the request was successfully processed, it will prevent any transaction that uses the same idempotency key, and was received within 24 hours of the first request, from being processed.

Max length: 128
Min length: 1
wallet_id
requiredstring
The ID of the e-wallet to debit from

Min length: 1
counterparty
requiredobject
An object representing the e-wallet transaction's counterparty
name
requiredstring
The name of the counterparty

Min length: 1
numbers
requiredobject
The counterparty's bank account numbers. Exactly one of IBAN or BACS data is required.
bacs
object
An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
international
object
International Bank Account Number for a Wallet Transaction
iban
string
International Bank Account Number (IBAN).

Min length: 15
Max length: 34
address
object
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
street
required[string]
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters.

Min items: 1
Min length: 1
city
requiredstring
The city where the recipient is located. Maximum of 35 characters.

Min length: 1
Max length: 35
postal_code
requiredstring
The postal code where the recipient is located. Maximum of 16 characters.

Min length: 1
Max length: 16
country
requiredstring
The ISO 3166-1 alpha-2 country code where the recipient is located.

Min length: 2
Max length: 2
date_of_birth
string
The counterparty's birthdate, in ISO 8601 (YYYY-MM-DD) format.

Format: date
amount
requiredobject
The amount and currency of a transaction
iso_currency_code
requiredstring
An ISO-4217 currency code, used with e-wallets and transactions.

Possible values: GBP, EUR
Min length: 3
Max length: 3
value
requirednumber
The amount of the transaction. Must contain at most two digits of precision e.g. 1.23.

Format: double
Minimum: 0.01
reference
requiredstring
A reference for the transaction. This must be an alphanumeric string with 6 to 18 characters and must not contain any special characters or spaces. Ensure that the reference field is unique for each transaction.

Max length: 18
Min length: 6
Select Language
1const request: WalletTransactionExecuteRequest = {
2  wallet_id: walletID,
3  counterparty: {
4    name: 'Test',
5    numbers: {
6      bacs: {
7        account: '12345678',
8        sort_code: '123456',
9      },
10    },
11  },
12  amount: {
13    value: 1,
14    iso_currency_code: 'GBP',
15  },
16  reference: 'transaction ABC123',
17  idempotency_key: '39fae5f2-b2b4-48b6-a363-5328995b2753',
18};
19try {
20  const response = await plaidClient.walletTransactionExecute(request);
21  const transactionID = response.data.transaction_id;
22  const status = response.data.status;
23} catch (error) {
24  // handle error
25}
wallet/transaction/execute

Response fields and example

transaction_id
string
A unique ID identifying the transaction
status
string
The status of the transaction.
AUTHORISING: The transaction is being processed for validation and compliance.
INITIATED: The transaction has been initiated and is currently being processed.
EXECUTED: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions.
SETTLED: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used.
FAILED: The transaction failed to process successfully. This is a terminal status.
BLOCKED: The transaction has been blocked for violating compliance rules. This is a terminal status.

Possible values: AUTHORISING, INITIATED, EXECUTED, SETTLED, BLOCKED, FAILED
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transaction_id": "wallet-transaction-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
3  "status": "EXECUTED",
4  "request_id": "4zlKapIkTm8p5KM"
5}
Was this helpful?

/wallet/transaction/get

Fetch an e-wallet transaction

Fetch a specific e-wallet transaction

wallet/transaction/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
transaction_id
requiredstring
The ID of the transaction to fetch

Min length: 1
Select Language
1const request: WalletTransactionGetRequest = {
2  transaction_id: transactionID,
3};
4try {
5  const response = await plaidClient.walletTransactionGet(request);
6  const transactionID = response.data.transaction_id;
7  const reference = response.data.reference;
8  const type = response.data.type;
9  const amount = response.data.amount;
10  const counterparty = response.data.counterparty;
11  const status = response.data.status;
12  const createdAt = response.created_at;
13} catch (error) {
14  // handle error
15}
wallet/transaction/get

Response fields and example

transaction_id
string
A unique ID identifying the transaction
wallet_id
string
The EMI (E-Money Institution) wallet that this payment is associated with, if any. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests.
reference
string
A reference for the transaction
type
string
The type of the transaction. The supported transaction types that are returned are: BANK_TRANSFER: a transaction which credits an e-wallet through an external bank transfer.
PAYOUT: a transaction which debits an e-wallet by disbursing funds to a counterparty.
PIS_PAY_IN: a payment which credits an e-wallet through Plaid's Payment Initiation Services (PIS) APIs. For more information see the Payment Initiation endpoints.
REFUND: a transaction which debits an e-wallet by refunding a previously initiated payment made through Plaid's PIS APIs.
FUNDS_SWEEP: an automated transaction which debits funds from an e-wallet to a designated client-owned account.

Possible values: BANK_TRANSFER, PAYOUT, PIS_PAY_IN, REFUND, FUNDS_SWEEP
scheme
nullablestring
The payment scheme used to execute this transaction. This is present only for transaction types PAYOUT and REFUND.
FASTER_PAYMENTS: The standard payment scheme within the UK.
SEPA_CREDIT_TRANSFER: The standard payment to a beneficiary within the SEPA area.
SEPA_CREDIT_TRANSFER_INSTANT: Instant payment to a beneficiary within the SEPA area.

Possible values: null, FASTER_PAYMENTS, SEPA_CREDIT_TRANSFER, SEPA_CREDIT_TRANSFER_INSTANT
amount
object
The amount and currency of a transaction
iso_currency_code
string
An ISO-4217 currency code, used with e-wallets and transactions.

Possible values: GBP, EUR
Min length: 3
Max length: 3
value
number
The amount of the transaction. Must contain at most two digits of precision e.g. 1.23.

Format: double
Minimum: 0.01
counterparty
object
An object representing the e-wallet transaction's counterparty
name
string
The name of the counterparty

Min length: 1
numbers
object
The counterparty's bank account numbers. Exactly one of IBAN or BACS data is required.
bacs
nullableobject
An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
international
nullableobject
International Bank Account Number for a Wallet Transaction
iban
string
International Bank Account Number (IBAN).

Min length: 15
Max length: 34
address
nullableobject
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
street
[string]
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters.

Min items: 1
Min length: 1
city
string
The city where the recipient is located. Maximum of 35 characters.

Min length: 1
Max length: 35
postal_code
string
The postal code where the recipient is located. Maximum of 16 characters.

Min length: 1
Max length: 16
country
string
The ISO 3166-1 alpha-2 country code where the recipient is located.

Min length: 2
Max length: 2
date_of_birth
nullablestring
The counterparty's birthdate, in ISO 8601 (YYYY-MM-DD) format.

Format: date
status
string
The status of the transaction.
AUTHORISING: The transaction is being processed for validation and compliance.
INITIATED: The transaction has been initiated and is currently being processed.
EXECUTED: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions.
SETTLED: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used.
FAILED: The transaction failed to process successfully. This is a terminal status.
BLOCKED: The transaction has been blocked for violating compliance rules. This is a terminal status.

Possible values: AUTHORISING, INITIATED, EXECUTED, SETTLED, BLOCKED, FAILED
created_at
string
Timestamp when the transaction was created, in ISO 8601 format.

Format: date-time
last_status_update
string
The date and time of the last time the status was updated, in IS0 8601 format

Format: date-time
payment_id
nullablestring
The payment id that this transaction is associated with, if any. This is present only for transaction types PIS_PAY_IN and REFUND.
failure_reason
nullablestring
The error code of a failed transaction. Error codes include: EXTERNAL_SYSTEM: The transaction was declined by an external system. EXPIRED: The transaction request has expired. CANCELLED: The transaction request was rescinded. INVALID: The transaction did not meet certain criteria, such as an inactive account or no valid counterparty, etc. UNKNOWN: The transaction was unsuccessful, but the exact cause is unknown.

Possible values: EXTERNAL_SYSTEM, EXPIRED, CANCELLED, INVALID, UNKNOWN
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transaction_id": "wallet-transaction-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
3  "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
4  "type": "PAYOUT",
5  "reference": "Payout 99744",
6  "amount": {
7    "iso_currency_code": "GBP",
8    "value": 123.12
9  },
10  "status": "EXECUTED",
11  "created_at": "2020-12-02T21:14:54Z",
12  "last_status_update": "2020-12-02T21:15:01Z",
13  "counterparty": {
14    "numbers": {
15      "bacs": {
16        "account": "31926819",
17        "sort_code": "601613"
18      }
19    },
20    "name": "John Smith"
21  },
22  "request_id": "4zlKapIkTm8p5KM"
23}
Was this helpful?

/wallet/transaction/list

List e-wallet transactions

This endpoint lists the latest transactions of the specified e-wallet. Transactions are returned in descending order by the created_at time.

wallet/transaction/list

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
wallet_id
requiredstring
The ID of the e-wallet to fetch transactions from

Min length: 1
cursor
string
A base64 value representing the latest transaction that has already been requested. Set this to next_cursor received from the previous /wallet/transaction/list request. If provided, the response will only contain transactions created before that transaction. If omitted, the response will contain transactions starting from the most recent, and in descending order by the created_at time.

Max length: 256
count
integer
The number of transactions to fetch

Minimum: 1
Maximum: 200
Default: 10
options
object
Additional wallet transaction options
start_time
string
Timestamp in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) for filtering transactions, inclusive of the provided date.

Format: date-time
end_time
string
Timestamp in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) for filtering transactions, inclusive of the provided date.

Format: date-time
Select Language
1const request: WalletTransactionListRequest = {
2  wallet_id: walletID,
3  count: 10,
4};
5try {
6  const response = await plaidClient.walletTransactionList(request);
7  const transactions = response.data.transactions;
8  const nextCursor = response.data.next_cursor;
9} catch (error) {
10  // handle error
11}
wallet/transaction/list

Response fields and example

transactions
[object]
An array of transactions of an e-wallet, associated with the given wallet_id
transaction_id
string
A unique ID identifying the transaction
wallet_id
string
The EMI (E-Money Institution) wallet that this payment is associated with, if any. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests.
reference
string
A reference for the transaction
type
string
The type of the transaction. The supported transaction types that are returned are: BANK_TRANSFER: a transaction which credits an e-wallet through an external bank transfer.
PAYOUT: a transaction which debits an e-wallet by disbursing funds to a counterparty.
PIS_PAY_IN: a payment which credits an e-wallet through Plaid's Payment Initiation Services (PIS) APIs. For more information see the Payment Initiation endpoints.
REFUND: a transaction which debits an e-wallet by refunding a previously initiated payment made through Plaid's PIS APIs.
FUNDS_SWEEP: an automated transaction which debits funds from an e-wallet to a designated client-owned account.

Possible values: BANK_TRANSFER, PAYOUT, PIS_PAY_IN, REFUND, FUNDS_SWEEP
scheme
nullablestring
The payment scheme used to execute this transaction. This is present only for transaction types PAYOUT and REFUND.
FASTER_PAYMENTS: The standard payment scheme within the UK.
SEPA_CREDIT_TRANSFER: The standard payment to a beneficiary within the SEPA area.
SEPA_CREDIT_TRANSFER_INSTANT: Instant payment to a beneficiary within the SEPA area.

Possible values: null, FASTER_PAYMENTS, SEPA_CREDIT_TRANSFER, SEPA_CREDIT_TRANSFER_INSTANT
amount
object
The amount and currency of a transaction
iso_currency_code
string
An ISO-4217 currency code, used with e-wallets and transactions.

Possible values: GBP, EUR
Min length: 3
Max length: 3
value
number
The amount of the transaction. Must contain at most two digits of precision e.g. 1.23.

Format: double
Minimum: 0.01
counterparty
object
An object representing the e-wallet transaction's counterparty
name
string
The name of the counterparty

Min length: 1
numbers
object
The counterparty's bank account numbers. Exactly one of IBAN or BACS data is required.
bacs
nullableobject
An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
international
nullableobject
International Bank Account Number for a Wallet Transaction
iban
string
International Bank Account Number (IBAN).

Min length: 15
Max length: 34
address
nullableobject
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
street
[string]
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters.

Min items: 1
Min length: 1
city
string
The city where the recipient is located. Maximum of 35 characters.

Min length: 1
Max length: 35
postal_code
string
The postal code where the recipient is located. Maximum of 16 characters.

Min length: 1
Max length: 16
country
string
The ISO 3166-1 alpha-2 country code where the recipient is located.

Min length: 2
Max length: 2
date_of_birth
nullablestring
The counterparty's birthdate, in ISO 8601 (YYYY-MM-DD) format.

Format: date
status
string
The status of the transaction.
AUTHORISING: The transaction is being processed for validation and compliance.
INITIATED: The transaction has been initiated and is currently being processed.
EXECUTED: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions.
SETTLED: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used.
FAILED: The transaction failed to process successfully. This is a terminal status.
BLOCKED: The transaction has been blocked for violating compliance rules. This is a terminal status.

Possible values: AUTHORISING, INITIATED, EXECUTED, SETTLED, BLOCKED, FAILED
created_at
string
Timestamp when the transaction was created, in ISO 8601 format.

Format: date-time
last_status_update
string
The date and time of the last time the status was updated, in IS0 8601 format

Format: date-time
payment_id
nullablestring
The payment id that this transaction is associated with, if any. This is present only for transaction types PIS_PAY_IN and REFUND.
failure_reason
nullablestring
The error code of a failed transaction. Error codes include: EXTERNAL_SYSTEM: The transaction was declined by an external system. EXPIRED: The transaction request has expired. CANCELLED: The transaction request was rescinded. INVALID: The transaction did not meet certain criteria, such as an inactive account or no valid counterparty, etc. UNKNOWN: The transaction was unsuccessful, but the exact cause is unknown.

Possible values: EXTERNAL_SYSTEM, EXPIRED, CANCELLED, INVALID, UNKNOWN
next_cursor
string
Cursor used for fetching transactions created before the latest transaction provided in this response
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "next_cursor": "YWJjMTIzIT8kKiYoKSctPUB",
3  "transactions": [
4    {
5      "transaction_id": "wallet-transaction-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
6      "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
7      "type": "PAYOUT",
8      "reference": "Payout 99744",
9      "amount": {
10        "iso_currency_code": "GBP",
11        "value": 123.12
12      },
13      "status": "EXECUTED",
14      "created_at": "2020-12-02T21:14:54Z",
15      "last_status_update": "2020-12-02T21:15:01Z",
16      "counterparty": {
17        "numbers": {
18          "bacs": {
19            "account": "31926819",
20            "sort_code": "601613"
21          }
22        },
23        "name": "John Smith"
24      }
25    },
26    {
27      "transaction_id": "wallet-transaction-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
28      "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
29      "type": "PAYOUT",
30      "reference": "Payout 99744",
31      "amount": {
32        "iso_currency_code": "EUR",
33        "value": 456.78
34      },
35      "status": "EXECUTED",
36      "created_at": "2020-12-02T21:14:54Z",
37      "last_status_update": "2020-12-02T21:15:01Z",
38      "counterparty": {
39        "numbers": {
40          "international": {
41            "iban": "GB33BUKB20201555555555"
42          }
43        },
44        "name": "John Smith"
45      }
46    }
47  ],
48  "request_id": "4zlKapIkTm8p5KM"
49}
Was this helpful?

Webhooks

Updates are sent to indicate that the status of transaction has changed. All virtual account webhooks have a webhook_type of WALLET.

WALLET_TRANSACTION_STATUS_UPDATE

Fired when the status of a wallet transaction has changed.

webhook_type
string
WALLET
webhook_code
string
WALLET_TRANSACTION_STATUS_UPDATE
transaction_id
string
The transaction_id for the wallet transaction being updated
payment_id
string
The payment_id associated with the transaction. This will be present in case of REFUND and PIS_PAY_IN
wallet_id
string
The EMI (E-Money Institution) wallet that this payment is associated with. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests.
new_status
string
The status of the transaction.
AUTHORISING: The transaction is being processed for validation and compliance.
INITIATED: The transaction has been initiated and is currently being processed.
EXECUTED: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions.
SETTLED: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used.
FAILED: The transaction failed to process successfully. This is a terminal status.
BLOCKED: The transaction has been blocked for violating compliance rules. This is a terminal status.

Possible values: AUTHORISING, INITIATED, EXECUTED, SETTLED, BLOCKED, FAILED
old_status
string
The status of the transaction.
AUTHORISING: The transaction is being processed for validation and compliance.
INITIATED: The transaction has been initiated and is currently being processed.
EXECUTED: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions.
SETTLED: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used.
FAILED: The transaction failed to process successfully. This is a terminal status.
BLOCKED: The transaction has been blocked for violating compliance rules. This is a terminal status.

Possible values: AUTHORISING, INITIATED, EXECUTED, SETTLED, BLOCKED, FAILED
timestamp
string
The timestamp of the update, in ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z"

Format: date-time
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "WALLET",
3  "webhook_code": "WALLET_TRANSACTION_STATUS_UPDATE",
4  "transaction_id": "wallet-transaction-id-production-2ba30780-d549-4335-b1fe-c2a938aa39d2",
5  "payment_id": "payment-id-production-feca8a7a-5591-4aef-9297-f3062bb735d3",
6  "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
7  "new_status": "SETTLED",
8  "old_status": "INITIATED",
9  "timestamp": "2017-09-14T14:42:19.350Z",
10  "environment": "production"
11}
Was this helpful?

errors api

API Errors

Guide to troubleshooting API errors

INTERNAL_SERVER_ERROR or plaid-internal-error

Plaid was unable to process the request
Sample user-facing error message
Something went wrong: There was a problem and we couldn't connect your account. Try entering your username and password again.
Link user experience

Your user will be redirected to the Institution Select pane to retry connecting their Item or a different account.

Common causes
  • Plaid received an unsupported response from a financial institution, which frequently corresponds to an institution error.
  • Plaid is experiencing internal system issues.
  • A product endpoint request was made for an Item at an OAuth-based institution, but the end user did not authorize the Item for the specific product, or has revoked Plaid's access to the product. Note that for some institutions, the end user may need to specifically opt-in during the OAuth flow to share specific details, such as identity data, or account and routing number information, even if they have already opted in to sharing information about a specific account.
Troubleshooting steps

If the error persists, please submit a Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

1http code 500
2{
3 "error_type": "API_ERROR",
4 "error_code": "INTERNAL_SERVER_ERROR",
5 "error_message": "an unexpected error occurred",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

PLANNED_MAINTENANCE

Plaid's systems are undergoing maintenance and API operations are disabled
Sample user-facing error message
Please try connecting a different account: There was a problem processing your request. Your account could not be connected at this time
Link user experience

Your user will be redirected to the Institution Select pane to retry connecting their Item or a different account.

Common causes
  • Plaid's systems are under maintenance and API operations are temporarily disabled. Advance notice will be provided when a maintenance window is planned.
Troubleshooting steps

If you have not been previously informed of planned maintenance, please reach out to Plaid Support for more information.

1http code 503
2{
3 "error_type": "API_ERROR",
4 "error_code": "PLANNED_MAINTENANCE",
5 "error_message": "the Plaid API is temporarily unavailable due to planned maintenance. visit https://status.plaid.com/ for more information",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

link data transparency messaging migration guide

(Beta) Data Transparency Messaging Migration Guide

How to enable Data Transparency Messaging for your application

Introduction

Plaid has introduced Data Transparency Messaging into the Link flow as a beta product. This experience provides users with a greater understanding of the types of data that they share with you and Plaid. When using Data Transparency Messaging, a user is informed of the specific data types that you are requesting and the reason that you are requesting them. If you want access to additional data from a user after their initial Link, they must consent to sharing that data through a separate consent flow.

This guide covers the client and server-side changes required to implement the Data Transparency Messaging feature.

What's new
  • The API will only return data for products provided in your Link configuration. In addition to the existing products field, we have added a new configuration field called additional_consented_products that can be used to gather consent for additional products.
  • The consent pane can be configured to display a pop-up that allows users to see what data is being requested. You will be able to specify your use case and why you need the data on the pop-up. There is also an option to add a standalone Data Transparency Messaging pane between institution select and credentials in addition to the consent pane for customers who want to make data transparency even more visible in the Link flow.
  • Products not provided in the Link configuration can not be accessed without going through update mode.

Migration overview

  1. Review the implementation considerations.
  2. Review your API integration and potentially add the additional_consented_products field with products you want to gather consent for prior to enabling. Every product that you currently use should be included in either the products or additional_consented_products fields.
  3. Update Link customizations to enable Data Transparency Messaging
  4. (Optional) Configure update mode to collect consent in the future

Implementation considerations

Previously, as long as you were approved and enabled for a product during your Plaid Dashboard Production Request process, you could request and start using it by calling the corresponding product API route on any Item. Going forward, any Item that goes through Link with Data Transparency Messaging enabled restricts your access to new product data unless new consent is collected through update mode. This behavior does not apply to Items created prior to enabling Data Transparency Messaging.

If you anticipate upgrading to a product in the future, or if you currently use a product but don’t want Plaid to try to extract that data immediately, you can create a Link token with additional_consented_products. These products will be shown in Link as part of Data Transparency Messaging, but will not be fetched or billed until you request them. Writing to the additional_consented_products field prior to enabling Data Transparency Messaging will not have any impact on your current Items, but it is recommended that you do so to ensure that new Items will have all of the proper permissions once you enable the feature.

Products placed in the additional_consented_products field do not have any impact on institution filtering or account subtype filtering. For example, if auth is an additional_consented_product, users will be allowed to select any account, not just checking/savings accounts.

Update Link customizations

To opt into Data Transparency Messaging, go to your Link customization or create a new one (you may duplicate an existing customization by using the duplicate feature), click on the Data Transparency Tab on the Consent Pane and enable the toggle. After enabling the toggle, you can customize the use case. Be aware that turning this feature on also changes the content on the Consent Pane. You can view the updated content in the General tab.

In addition to the updated Consent Pane, you can also enable a standalone Data Transparency Messaging pane for additional transparency. To do that, navigate to the Data Transparency pane and enable the feature. This pane works together with the Consent Pane, so the feature must first be enabled on the Consent Pane in order to enable the standalone pane, and both will be present in the flow. The use case on the standalone pane is shared with the use case on the Consent Pane popup, and can only be customized there.

Once you’ve selected how you want to present Data Transparency Messaging to consumers and written your use case, click Publish. Your changes will go into effect the next time you initialize Link with this customization. Only newly created Items created with the updated customization will have the new API behavior; existing Items will not be affected.

If you want to disable the feature, you can toggle it off in the Data Transparency tab and publish your changes.

If you currently use additional products after Link that you do not initialize via the products field, it is recommended that you update your /link/token/create code to include additional_consented_products before enabling this feature in the Plaid Dashboard to avoid losing access to the additional API endpoints on your new Items.

API changes

For Items that have gone through Link with Data Transparency Messaging enabled, there will be a new consented_products field returned by the /item/get endpoint, as well as all product endpoints. This field contains all of the products that consent has been collected for on this Item.

For Items with the consented_products field set, you will see the error code ADDITIONAL_CONSENT_REQUIRED if you do not have consent to a product you are trying to request. This is the same error you would get if you are not enabled for the product.

Certain financial institutions implement opt-outs for sharing data types in their OAuth flow. If a user opts out of sharing certain financial data, you may be blocked from accessing certain product routes. This error code will be returned as ACCESS_NOT_GRANTED.

To resolve ADDITIONAL_CONSENT_REQUIRED errors, you should send the user through update mode with all of the products you want consent for. To resolve ACCESS_NOT_GRANTED errors, you should send the user through update mode to do an Item repair. No products should be passed in with this request. We also recommend providing the user with context on what data you are requesting and why, prior to launching update mode, so they are more likely to give consent.

New SDK events and view names for the Data Transparency Messaging consent pane and standalone pane have also been added. The new view names are DATA_TRANSPARENCY and DATA_TRANSPARENCY_CONSENT. The new event is VIEW_DATA_TYPES, which is triggered when a user views the popup data type modal on the Consent Pane.

Data types and consent

The products you request for Link Initialization are not mapped 1:1 with the different data types displayed. Our goal is to allow consumers to understand what types of data they are permissioning, and product names alone can be confusing to consumers. Because data types can be broad, in certain cases, you will get consent for more than just the products you initialize Link with. For example, the Assets product requires consent to both the "Transactions" and the "Account Holder Information" data types, so the Transactions and Identity products will both be consented to by default. To understand which products you have consent to access for a given Item, you can use the consented_products field on the /item/get or product endpoints as detailed above.

Data types
Account and balance info
May include account details such as account name, type, description, balances, and masked account number.
Contact details
May include account owner name, email, phone, and address.
Account and routing numbers
Includes your account and bank routing number.
Transactions
May include transaction details such as amounts, dates, price, location, spending categories and descriptions, and insights like recurring transactions.
Credit and loans
May include details about your credit and loan accounts, such as balance, payment dates and amounts due, credit limit, repayment status, interest rate, loan terms, and originator info.
Investments
May include info about investment accounts, such as securities details, quantity, price, and transactions.
Payroll info
May include income or employment data, such as gross earnings, check amount, as well as other earnings or employment info.
Transaction risk info
May include account info such as activity and usage, holder info, and Plaid connection history.

Requesting consent for additional products in update mode

If you would like to start collecting product data for an Item that you did not collect enough consent for during initial creation, you are able to send that item through update mode to collect new consent. To add this additional consent, initialize Link for update mode. For OAuth institutions, ensure you configure the Link token with a redirect URI, as described in Configure your Link token with your redirect URI. Your call to /link/token/create should include the following:

  • The additional_consented_products field should be set to include any new products you want to gather consent for.
    • For example, if Link was initialized with just Transactions and you want to upgrade to Identity, you would pass in identity to the additional_consented_products field.
    • To see the currently authorized and consented products on an Item, use the /item/get endpoint
  • The link_customization_name should be set to a customization with Data Transparency Messaging enabled. The use case string should also be broadened to include your reasons for accessing the new data. If the use case is not customized, the default use case will be present on the Data Transparency Messaging pane.

If the upgrade was successful, you will receive the onSuccess() callback and you will have access to the API endpoints for all of the products you passed into Link update mode. The new products will only be billed once the related API endpoints are called, even if they would otherwise be billed upon Item initialization (e.g., Transactions).

Using Data Transparency Messaging with legacy public key integrations

The Data Transparency experience is compatible with legacy public key integrations, but the additional_consented_products configuration field will not be usable. All products will have to be passed in through the standard products field.

Minimum client library version for using additional consented products

api libraries

Libraries

Learn about libraries and SDKs to easily integrate with the Plaid APIs

All libraries for Plaid are listed below. If you've built anything that you'd be willing to share with the Plaid community, please let us know and we'll link to it here!

Client libraries

Plaid offers official API libraries for different programming languages, which are regularly updated for breaking and non-breaking API changes. These client libraries are generated from our OpenAPI file.

Node logo

Node

plaid-node

Python logo

Python

plaid-python

Ruby logo

Ruby

plaid-ruby

Java logo

Java

plaid-java

Go logo

Go

plaid-go

Community libraries

Explore some of the community-supported libraries available for Plaid listed below. If you built your own library, please reach out to our Support team to add it to this list! The best way to create your own library is by using the Plaid OpenAPI file.

Note that community libraries are not officially supported by Plaid. Plaid cannot provide assistance with using these libraries or guarantee that they will be kept up-to-date with all the changes needed to support the latest modifications to the Plaid API.

Elixir

by @tylerwray

Elixir

by @wfgilman

.NET

Going.Plaid, by @viceroypenguin

PHP

by @TomorrowIdeas

Rust

by @telcoin

Link client SDKs

For information on Plaid's front-end SDKs for web and mobile, see Link.

To learn more about installing and using Link SDKs, check out the docs pages for Link on JavaScript and React (web), React Native, iOS, Android, and Webviews.

Note that libraries marked as (community) are not officially supported by Plaid. Plaid cannot provide assistance with using these libraries or guarantee that they will be kept up-to-date with all the changes needed to support the latest modifications to the Plaid API.

iOS logo

iOS

plaid-link-ios

Android logo

Android

plaid-link-android

React logo

React

react-plaid-link

React Native logo

React Native

react-native-plaid-link-sdk

Angular

by Mike Roberts (community)

Flutter

by @jorgefspereira (community)

Quickstart & example apps

For a listing of Plaid sample apps, see the Resources page.

auth partnerships check

Add Check to your app

Use Check with Plaid Auth to send and receive payments!

Partnership Check logo

Overview

Plaid and Check have partnered to easily configure direct deposit for employees on payroll. With Check’s payroll-as-a-service API, you can easily embed payroll in your product. This integration enables Check’s customers to connect employee bank accounts in seconds through Plaid’s trusted Auth flow. Check’s customers will then generate a Processor token on behalf of the employee, and then pass that token to Check. The token allows Check to immediately retrieve account details, eliminating the need for customers to hold sensitive bank information.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Check account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Check processor_token, which allows you to quickly and securely verify a bank funding source via Check's API without having to store any sensitive banking information. Utilizing Plaid + Check enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Check in order to use the Plaid + Check integration. You'll also need to enable your Plaid account for the Check integration.

First, you will need to work with the Check team to sign up for a Check account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Check to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Check processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Check, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Check processor_token. You'll send this token to Check and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Check processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'check',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Check Production credentials prior to initiating live payment transactions in the Check API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

auth partnerships marqeta

Add Marqeta to your app

Use Marqeta with Plaid Auth to send and receive payments!

Partnership Marqeta logo

Overview

Plaid and Marqeta have partnered to integrate Plaid’s data connectivity platform with Marqeta’s modern card-issuing platform.

    This integration will enable you to seamlessly create a validated funding source for a Marqeta-powered card:
  1. Instantly authenticate users’ bank accounts with Plaid Link (i.e. optimize user conversation, shorten wait times to verify the funding source, avoid Microdeposits).
  2. Securely share tokenized banking data to integrate with Marqeta’s ACH Origination solution.

To help maintain the highest levels of data security, this partner integration will tokenize all sensitive bank account information to limit exposing personally identifiable information (PII).

Value Props

  • Marqeta and Plaid have partnered on an integration to enable clients to instantly authenticate consumer and business accounts with Plaid, and securely share authenticated payment information with Marqeta for card account funding.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Marqeta account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Marqeta processor_token, which allows you to quickly and securely verify a bank funding source via Marqeta's API without having to store any sensitive banking information. Utilizing Plaid + Marqeta enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Marqeta in order to use the Plaid + Marqeta integration. You'll also need to enable your Plaid account for the Marqeta integration.

First, you will need to work with the Marqeta team to sign up for a Marqeta account, if you do not already have one. Once your account is active, you then need to work with your Marqeta representative to request enablement of the Plaid integration for your program’s private sandbox.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Marqeta to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Marqeta processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Marqeta, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Marqeta processor_token. You'll send this token to Marqeta and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Marqeta processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'marqeta',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Marqeta Production credentials prior to initiating live payment transactions in the Marqeta API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

quickstart

Get started with the Quickstart

A quick introduction to building with Plaid

Want more video tutorials? The full getting started guide for the Quickstart app is available on YouTube.

Don't want to write code? Check out the Plaid Postman Collection for a no-code way to get started with Plaid's API.

Looking to get started with Identity Verification or Income Verification? For Identity Verification, check out the Identity Verification Quickstart. For Income, try the Income Verification Starter app.

Introduction

Let’s test out running Plaid locally by cloning the Quickstart app. You’ll need API keys, which you can receive by signing up in the Dashboard.

You'll have two different API keys, and there are three different Plaid environments. Today we'll start in the Sandbox environment. View the API Keys section of the Dashboard to find your Sandbox secret.

API Key
View Keys in Dashboard
client_id
Private identifier for your team
secret
Private key, one for each of the three environments
Environment
Sandbox
Get started with test credentials and life-like data
Development
Build out your app with up to 100 live credentials
Production
Launch your app with unlimited live credentials

If you get stuck at any point in the Quickstart, help is just a click away! Check the Quickstart troubleshooting guide, ask other developers in our Stack Overflow community or submit a Support ticket.

Quickstart setup

Once you have your API keys, it's time to run the Plaid Quickstart locally! The instructions below will guide you through the process of cloning the Quickstart repository, customizing the .env file with your own Plaid client ID and Sandbox secret, and finally, building and running the app.

Plaid offers both Docker and non-Docker options for the Quickstart. If you don't have Docker installed, you may wish to use the non-Docker version; this path is especially recommended for Windows users who do not have Docker installations. However, if you already have Docker installed, we recommend the Docker option because it is simpler and easier to run the Quickstart. Below are instructions on setting up the Quickstart with Docker and non-Docker configurations.

Select group for content switcher

Setting up without Docker

Make sure you have npm installed before following along. If you're using Windows, ensure you have a terminal capable of running basic Unix shell commands.

Select Language
1# Note: If on Windows, run
2# git clone -c core.symlinks=true https://github.com/plaid/quickstart
3# instead to ensure correct symlink behavior
4
5git clone https://github.com/plaid/quickstart.git
6cd quickstart/node
7
8# Copy the .env.example file to .env, then fill
9# out PLAID_CLIENT_ID and PLAID_SECRET in .env
10cp .env.example .env
11
12# Install dependencies
13npm install
14
15# Start the backend app
16./start.sh

Open a new shell and start the frontend app. Your app will be running at http://localhost:3000.

1# Install dependencies
2cd quickstart/frontend
3npm install
4
5# Start the frontend app
6npm start
7
8# Go to http://localhost:3000

Visit localhost and log in with Sandbox credentials (typically user_good and pass_good, as indicated at the bottom of the page).

Create your first Item

Most API requests interact with an Item, which is a Plaid term for a login at a financial institution. A single end-user of your application might have accounts at different financial institutions, which means they would have multiple different Items. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts.

Now that you have the Quickstart running, you’ll add your first Item in the Sandbox environment. Once you’ve opened the Quickstart app on localhost, click the Launch Link button and select any institution (other than Capital One, which is not supported in the Sandbox). Use the Sandbox credentials to simulate a successful login.

Sandbox credentials
1username: user_good
2password: pass_good
3If prompted to enter a 2FA code: 1234

Once you have entered your credentials and moved to the next screen, you have created your first Item! You can now make API calls for that Item by using the buttons in the Quickstart. In the next section, we'll explain what actually happened and how the Quickstart works.

How it works

As you might have noticed, you use both a server and a client-side component to access the Plaid APIs. The flow looks like this:

The Plaid flow begins when your user wants to connect their bank account to your app.
Step diagram
1Call /link/token/create to create a link_token and pass the temporary token to your app's client.
Step 1 diagram
2Use the link_token to open Link for your user. In the onSuccess callback, Link will provide a temporary public_token.
Step 2 diagram
3Call /item/public_token/exchange to exchange the public_token for a permanent access_token and item_id for the new Item.
Step 3 diagram
4Store the access_token and use it to make product requests for your user's Item.
Step 4 diagram

The first step is to create a new link_token by making a /link/token/create request and passing in the required configurations. This link_token is a short lived, one-time use token that authenticates your app with Plaid Link, our frontend module. Several of the environment variables you configured when launching the Quickstart, such as PLAID_PRODUCTS, are used as parameters for the link_token.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});

Once you have a link_token, you can use it to initialize Link. Link is a drop-in client-side module available for web, iOS, and Android that handles the authentication process. The Quickstart uses Link on the web, which is a pure JavaScript integration that you trigger via your own client-side code. This is what your users use to log into their financial institution accounts.

After a user submits their credentials within Link, Link provides you with a public_token via the onSuccess callback. The code below shows how the Quickstart passes the public_token from client-side code to the server. Both React and vanilla JavaScript examples are shown.

Select Language
1// APP COMPONENT
2// Upon rendering of App component, make a request to create and
3// obtain a link token to be used in the Link component
4import React, { useEffect, useState } from 'react';
5import { usePlaidLink } from 'react-plaid-link';
6const App = () => {
7  const [linkToken, setLinkToken] = useState(null);
8  const generateToken = async () => {
9    const response = await fetch('/api/create_link_token', {
10      method: 'POST',
11    });
12    const data = await response.json();
13    setLinkToken(data.link_token);
14  };
15  useEffect(() => {
16    generateToken();
17  }, []);
18  return linkToken != null ? <Link linkToken={linkToken} /> : <></>;
19};
20// LINK COMPONENT
21// Use Plaid Link and pass link token and onSuccess function
22// in configuration to initialize Plaid Link
23interface LinkProps {
24  linkToken: string | null;
25}
26const Link: React.FC<LinkProps> = (props: LinkProps) => {
27  const onSuccess = React.useCallback((public_token, metadata) => {
28    // send public_token to server
29    const response = fetch('/api/set_access_token', {
30      method: 'POST',
31      headers: {
32        'Content-Type': 'application/json',
33      },
34      body: JSON.stringify({ public_token }),
35    });
36    // Handle response ...
37  }, []);
38  const config: Parameters<typeof usePlaidLink>[0] = {
39    token: props.linkToken!,
40    receivedRedirectUri: window.location.href,
41    onSuccess,
42  };
43  const { open, ready } = usePlaidLink(config);
44  return (
45    <button onClick={() => open()} disabled={!ready}>
46      Link account
47    </button>
48  );
49};
50export default App;

Next, on the server side, the Quickstart calls /item/public_token/exchange to obtain an access_token, as illustrated in the code excerpt below. The access_token uniquely identifies an Item and is a required argument for most Plaid API endpoints. In your own code, you'll need to securely store your access_token in order to make API requests for that Item.

Select group for content switcher
Select Language
1app.post('/api/exchange_public_token', async function (
2  request,
3  response,
4  next,
5) {
6  const publicToken = request.body.public_token;
7  try {
8    const response = await client.itemPublicTokenExchange({
9      public_token: publicToken,
10    });
11
12    // These values should be saved to a persistent database and
13    // associated with the currently signed-in user
14    const accessToken = response.data.access_token;
15    const itemID = response.data.item_id;
16
17    res.json({ public_token_exchange: 'complete' });
18  } catch (error) {
19    // handle error
20  }
21});

Making API requests

Now that we've gone over the Link flow and token exchange process, we can explore what happens when you press a button in the Quickstart to make an API call. As an example, we'll look at the Quickstart's call to /accounts/get, which retrieves basic information, such as name and balance, about the accounts associated with an Item. The call is fairly straightforward and uses the access_token as a single argument to the Plaid client object.

Select group for content switcher
Select Language
1app.get('/api/accounts', async function (request, response, next) {
2  try {
3    const accountsResponse = await client.accountsGet({
4      access_token: accessToken,
5    });
6    prettyPrintResponse(accountsResponse);
7    response.json(accountsResponse.data);
8  } catch (error) {
9    prettyPrintResponse(error);
10    return response.json(formatError(error.response));
11  }
12});

Example response data:

1{
2  "accounts": [
3    {
4      "account_id": "A3wenK5EQRfKlnxlBbVXtPw9gyazDWu1EdaZD",
5      "balances": {
6        "available": 100,
7        "current": 110,
8        "iso_currency_code": "USD",
9        "limit": null,
10        "unofficial_currency_code": null
11      },
12      "mask": "0000",
13      "name": "Plaid Checking",
14      "official_name": "Plaid Gold Standard 0% Interest Checking",
15      "subtype": "checking",
16      "type": "depository"
17    },
18    {
19      "account_id": "GPnpQdbD35uKdxndAwmbt6aRXryj4AC1yQqmd",
20      "balances": {
21        "available": 200,
22        "current": 210,
23        "iso_currency_code": "USD",
24        "limit": null,
25        "unofficial_currency_code": null
26      },
27      "mask": "1111",
28      "name": "Plaid Saving",
29      "official_name": "Plaid Silver Standard 0.1% Interest Saving",
30      "subtype": "savings",
31      "type": "depository"
32    },
33    {
34      "account_id": "nVRK5AmnpzFGv6LvpEoRivjk9p7N16F6wnZrX",
35      "balances": {
36        "available": null,
37        "current": 1000,
38        "iso_currency_code": "USD",
39        "limit": null,
40        "unofficial_currency_code": null
41      },
42      "mask": "2222",
43      "name": "Plaid CD",
44      "official_name": "Plaid Bronze Standard 0.2% Interest CD",
45      "subtype": "cd",
46      "type": "depository"
47    }
48    ...
49  ],
50  "item": {
51    "available_products": [
52      "assets",
53      "balance",
54      "identity",
55      "investments",
56      "transactions"
57    ],
58    "billed_products": ["auth"],
59    "consent_expiration_time": null,
60    "error": null,
61    "institution_id": "ins_12",
62    "item_id": "gVM8b7wWA5FEVkjVom3ri7oRXGG4mPIgNNrBy",
63    "webhook": "https://requestb.in"
64  },
65  "request_id": "C3IZlexgvNTSukt"
66}

Next steps

Congratulations, you have completed the Plaid Quickstart! From here, we invite you to modify the Quickstart code in order to get more practice with the Plaid API. There are a few directions you can go in now:

Looking to move money with a Plaid partner, such as Dwolla or Stripe? See Move money with our partners for partner-specific money movement walkthroughs. You can also try out our account funding tutorial.

If you're not sure which Plaid products you want to use, see Explore by use case for a mapping of common use cases to corresponding products.

If you do know which product you want, you can go directly to its documentation. Products documented here are Auth, Transactions, Balance, Investments, Liabilities, Assets, Identity, Payment Initiation (UK and Europe), Virtual Accounts (UK and Europe), Income, Identity Verification and Monitor.

The Quickstart covered working with web apps. If your Plaid app will be on mobile, see Plaid Link to learn about getting started with mobile client-side setup.

For more sample apps, including a bare-bones minimal Plaid implementation and apps demonstrating real world examples of funds transfer and personal financial management, see sample apps.

errors income

Income errors

Guide to troubleshooting Income errors

INCOME_VERIFICATION_DOCUMENT_NOT_FOUND

The requested income verification document was not found.
Common causes
  • The document URL is incorrect (for example, it may contain a typo) or has expired.
  • The document URL has already been accessed. Document URLs can only be used once.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INCOME_VERIFICATION_ERROR",
4 "error_code": "INCOME_VERIFICATION_DOCUMENT_NOT_FOUND",
5 "error_message": "the requested data was not found. Please check the ID supplied.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INCOME_VERIFICATION_FAILED

The income verification you are trying to retrieve could not be completed. please try creating a new income verification
Common causes
  • The processing of the verification failed to complete successfully.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INCOME_VERIFICATION_ERROR",
4 "error_code": "INCOME_VERIFICATION_FAILED",
5 "error_message": "the income verification you are trying to retrieve could not be completed. please try creating a new income verification",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INCOME_VERIFICATION_NOT_FOUND

The requested income verification was not found.
Common causes
  • The Link flow has not been completed with income_verification enabled; either the user has not yet completed the Link flow, or the link token was not initialized with the income_verification product.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INCOME_VERIFICATION_ERROR",
4 "error_code": "INCOME_VERIFICATION_NOT_FOUND",
5 "error_message": "the requested data was not found. Please check the ID supplied.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INCOME_VERIFICATION_UPLOAD_ERROR

There was an error uploading income verification documents.
Common causes
  • The end user's Internet connection may have been interrupted during the upload attempt.
Troubleshooting steps
1http code 500
2{
3 "error_type": "INCOME_VERIFICATION_ERROR",
4 "error_code": "INCOME_VERIFICATION_UPLOAD_ERROR",
5 "error_message": "there was a problem uploading the document for verification. Please try again or recreate an income verification.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

PRODUCT_NOT_ENABLED

The Income product has not been enabled.
Common causes
  • The Income product has not been enabled.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INCOME_VERIFICATION_ERROR",
4 "error_code": "PRODUCT_NOT_ENABLED",
5 "error_message": "the 'income_verification' product is not enabled for the following client ID: <CLIENT_ID>. please ensure that the 'income_verification' is included in the 'product' array when initializing Link and try again.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

PRODUCT_NOT_READY

The Income product has not completed processing.
Common causes
  • Parsing of the uploaded pay stubs has not yet completed.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INCOME_VERIFICATION_ERROR",
4 "error_code": "PRODUCT_NOT_READY",
5 "error_message": "the requested product is not yet ready. please provide a webhook or try the request again later",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

VERIFICATION_STATUS_PENDING_APPROVAL

The user has not yet authorized the sharing of this data
Common causes
  • The user has not yet authorized access to the data.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INCOME_VERIFICATION_ERROR",
4 "error_code": "VERIFICATION_STATUS_PENDING_APPROVAL",
5 "error_message": "The user has not yet authorized the sharing of this data",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

EMPLOYMENT_NOT_FOUND

The requested employment was not found.
Common causes
  • The Link flow has not been completed with employment enabled; either the user has not yet completed the Link flow, or the link token was not initialized with the employment product.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INCOME_VERIFICATION_ERROR",
4 "error_code": "EMPLOYMENT_NOT_FOUND",
5 "error_message": "the requested employment data was not found. Please check the ID supplied.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

changelog

Plaid changelog

Track changes to the Plaid API and products

Overview

This changelog tracks updates to the Plaid API and major changes to the Plaid Dashboard, SDKs, functionality, and libraries. The changelog is updated at least once per month. Updates that affect only products or features in beta or limited release may not be reflected.

Link SDKs are released on a monthly cadence. For a complete record of Link SDK changes, see the GitHub changelogs: iOS, Android, React Native, React.

Plaid's officially supported libraries are updated on a monthly cadence. For details, see the GitHub changelogs: Python, Node, Ruby, Java, Go.

For a changelog view focused on new feature availability, see the Changelog on the Plaid blog.

Subscribe to updates

Subscribe to this changelog via RSS.

July 2023
  • Added /processor/token/webhook/update endpoint to allow customers using processor partners to update the webhook endpoint associated with a processor token.

For Assets:

  • Made asset_report_token optional in /asset_report/get request to support future development of Asset Reports based on other types of tokens.

For Investments:

For Enrich:

  • Added confidence_level to counterparty and personal_finance_category fields.

For Identity Verification:

  • Added date_of_birth and address fields to documentary_verification.documents[].extracted_data in the response of all Identity Verification endpoints.
  • Mark all region and postal_code fields as nullable, to better support countries that do not use these fields.

For Transfer:

  • Added transfer_id and status filters to /transfer/sweep/list request.
  • Added status field to the sweep object.
June 2023

  • Added the required_if_supported_products field to /link/token/create. When using multiple Plaid products, you can use this field to specify products that must be enabled when the user's institution and account type support them, while still allowing users to add Items if the institution or linked account doesn't support these products. If a product in this field cannot be enabled at a compatible institution (for example, because the user failed to grant the required OAuth permissions, generating an ACCESS_NOT_GRANTED error), the Item will not be created, and the user will be prompted to try again in the Link flow.

  • Changed the behavior of the oauth field on the institution object. Previously, oauth would be true only if all Items at an institution used OAuth connections. Now, oauth is true if any Items at an institution use OAuth connections.

  • Changed the behavior of the account_selection_enabled flag in /link/token/create. To improve conversion, at institutions that provide OAuth account selection flows, this flag will be overridden and treated as though it were always true. For other institutions, the flag behavior is unchanged.

For Auth:

  • Added the ability to customize Same-day Microdeposit flows via the new reroute_to_credentials option in /link/token/create. Using this field, you can detect whether a user is attempting to use Same-day Microdeposits to add an institution that is supported via a direct Plaid connection, and optionally either require or recommend that they use a direct connection instead.

For Enrich:

  • Added income_source enum to counterparty_type field.

For Identity Verification:

  • Added the ability to prefill user data when retrying a verification by providing a user object to /identity_verification/retry.
  • Added client_user_id field to /identity_verification/create. It is recommended to use this field instead of user.client_user_id, although both fields are supported.

For Income:

For Signal:

For Transfer:

  • Added the ability to specify a test_clock_id when calling /sandbox/transfer/sweep/simulate or /sandbox/transfer/simulate. If provided, the simulated action will take place at the virtual_time of the given test clock.
  • Made the virtual_time field optional when calling /sandbox/transfer/test_clock/create. If a time is not provided, the current time will be used.
  • Updated the sweep_id format to be either a UUID or an 8-character hexadecimal string.
  • Made next_origination_date nullable in the recurring transfer object.

For Virtual Accounts:

May 2023

For Assets:

For Identity:

For Identity Verification:

  • Added the selfie_check field to the Income Verification object, to report the status of a selfie check.

For Document Income:

For Transfers:

  • Increased the maximum length of the description field in /transfer/create to 15 characters.
  • Added the /transfer/balance/get endpoint.
  • To support prefunded credit processing, added the credit_funds_source field to distinguish between credits based on sweeps, RTP credit balances, and ACH credit balances, and made the funding_account_id field nullable.

For Processor partners:

For Signal:

April 2023

For Income:

For Document Income:

  • Released the /credit/payroll_income/risk_signals/get endpoint. This endpoint can be used as part of the Document Income flow to assess a user-uploaded document for signs of potential fraud or tampering.

For Identity Verification:

  • Documented several fields in the user object of /link/token/create as being officially supported methods of pre-filling user data in Link for the Identity Verification flow, as an alternative to /identity_verification/create. (While this worked in the past, it was not previously an officially supported or documented flow.) As part of this change, un-deprecated the user.date_of_birth field.

For Enrich:

March 2023
  • To maximize conversion, updated Link to use a pop-up window for OAuth authentication rather than redirects on non-webview mobile web flows.
  • Clarified that continue(from:) is no longer required for iOS OAuth integrations using Plaid's iOS and React Native iOS SDKs.
  • Updated error codes for most RATE_LIMIT errors to be specific to the endpoint for which they apply.

For Auth:

  • Changed the Link UI for Instant Match and Automated Micro-deposits flows to increase conversion by reducing the number of screens in the flow and removing unnecessary input fields. No developer action is required as a result of this change.

For Transactions:

For Identity:

  • Added /identity/match (beta) to simplify the process of using Identity for account ownership verification. /identity/match allows you to send user information such as name, address, email, and phone number, and returns a match score indicating how closely that data matches information on file with the financial institution, so that you no longer have to implement similarity matching logic on your own. /identity/match is currently in closed beta; to request access, contact your Account Manager or contact Sales.

For Identity Verification:

For Assets:

  • Released Fast Assets functionality to General Availability (GA). With Fast Assets, you can create a Fast Asset Report with partial information (current balance and identity data) in about half the time as a Full Asset Report, then request the Full Asset Report later. Fast Assets is available free of charge to all Assets customers. For more information, see the Assets API reference.
  • Added the optional days_to_include field to /asset_report/get requests. This field allows you to optionally reduce the number of days displayed in an Asset Report, to improve usability for human reviewers.
  • Added Freddie Mac as an audit copy token partner with auditor_id: freddie_mac.
  • Added credit_category (beta) to transactions data returned by Asset Reports with Insights, describing the category of the transaction. Access to this field is in closed beta; to request access, contact your Account Manager.

For Income:

  • Added support for bank_employment_results data to /credit/sessions/get. Employment functionality is currently in closed beta; for more details, contact your Account Manager.

For Signal:

For Virtual Accounts:

  • Added transaction_id to the Payment Initiation PAYMENT_STATUS_UPDATE webhook. This field will be present only when a payment was initiated using Virtual Accounts.
  • Added payment_id and wallet_id to the WALLET_TRANSACTION_STATUS_UPDATE webhook.
February 2023
  • Added the persistent_account_id field (beta) to the account object. The persistent_account_id field identifies an account across multiple instances of the same Item, for use with Chase Items only, to simplify the management of Chase duplicate Item behavior. Access to this field is currently in closed beta; for more details, contact your Account Manager.

For Assets:

  • Beginning March 31, 2023, Assets will be updated to return investment, instead of brokerage, as the account type for investment accounts. brokerage may still be returned as an account sub-type under the investment account type.

For Income:

  • Added employment value to the products array for /link/token/create. Employment functionality is currently in closed beta; for more details, contact your account manager.

For Identity Verification:

  • Added redacted_at field in Identity Verification response and Documentary Verification Document component.

For Transfer:

For reseller partners:

For Virtual Accounts:

For Payment Initiation:

For Signal:

  • Added signal to the products array. For most current Signal customers, Signal is automatically enabled for all of their Items; over time, Signal will be moving to a model similar to Plaid's other products, in which customers instead initialize an Item with signal by adding signal to the products array when calling /link/token/create.
January 2023
  • Released Plaid React Native SDK 9.0.0 and Plaid iOS SDK 4.1.0. All iOS integrations must upgrade to these SDKs by June 30, 2023 in order to maintain support for Chase OAuth flows on iOS. Any integrations using webviews will also be required to update their webview handlers by June 30, 2023. For more details on required webview updates, see the OAuth Guide.
  • Released improvements to the Returning User Experience (RUX): removing the requirement to provide a verified time for phone numbers and email addresses, making RUX flows available for more products, and adding Institution Boosting, which automatically surfaces institutions a user has previously linked to Plaid in the Link flow. Enabling RUX can increase conversion by 8% or more. For more details on how to enable RUX, see Returning User Experience documentation.

For Auth:

  • Updated Same-Day Micro-deposits to make a single one-cent micro-deposit, which will not be reversed, rather than multiple micro-deposits. This change will reduce costs and decrease the incentive for micro-deposit fraud. No changes are required on the part of developers to support this change. This change will automatically be rolled out to customers over the next several months.

For Transfer:

  • Added expected_settlement_date field to the Transfer object.
  • Added funding_account_id field to clarify which account is used to fund a transfer. This field replaces the older origination_account_id.

For Virtual Accounts:

  • Added status field to Wallet schema.

For Partners:

December 2022

For Auth:

  • Announced upcoming Instant Match automatic enrollment to existing customers who have not yet been enabled for Instant Match by default. Instant Match is a higher-converting experience for Link that expands Auth coverage to more end users. All customers will be enabled for Instant Match by default unless they opt-out by January 19, 2023, which they can do by contacting their Account Manager.

For Assets:

For Income:

  • For /credit/bank_income/get, deprecated amount, iso_currency_code, and unofficial_currency_code at top levels in response in favor of new total_amounts field. This change enables more accurate reporting of income for users with income in multiple different currencies.
  • Added new possible values to rate_of_pay field returned by /credit/payroll_income/get: WEEKLY, BI_WEEKLY, MONTHLY, SEMI_MONTHLY, DAILY, and COMMISSION.
  • Added new pay_basis field to the response of /credit/payroll_income/get.

For Virtual Accounts:

  • Added FUNDS_SWEEP as a possible transaction type.

For Transfer:

For Enrich:

  • Released Enrich to Early Availability. Enrich access is now available by default in Sandbox. For details on requesting access to use Enrich with real data, see the Enrich documentation.
  • Added support for legacy categories, using categories from /categories/get, in addition to the newer personal_finance_category schema.
  • Renamed counterparty type delivery_marketplace to marketplace and added counterparty type payment_terminal.

For the Reseller Partner API:

November 2022
  • Released Signal to general availability. Signal uses machine learning techniques to evaluate a proposed ACH transaction and determine the likelihood that the transaction will be reversed. It also provides fields and insights that you can incorporate into your own data models. By using the Signal API, you can release funds earlier to optimize your user experience while managing the risk of ACH returns.

For Auth:

For Investments:

  • Notified customers that customers must hold a CGS (CUSIP Global Services) license to obtain CUSIP and ISIN data. Beginning in mid-September 2023, customers who do not have a record of this license with Plaid will receive null data in these fields. To maintain access to these fields, contact your Plaid Account Manager or investments-vendors@plaid.com.

For Payment Initiation:

  • Added the ability to initiate partial refunds by specifying an amount when calling /payment_initiation/payment/reverse. As part of this change, added amount_refunded field to /payment_initiation/payment/get and /payment_initiation/payment/list.
  • Added support for local payment schemes for all supported currencies (previously, only EUR and GBP local payment schemes been supported), and added the enum values LOCAL_DEFAULT and LOCAL_INSTANT to represent them. In the UK, the FASTER_PAYMENTS enum value has been replaced by LOCAL_DEFAULT.
  • Removed support for currencies CHF and CZK.

For Virtual Accounts:

For Transfer:

For Reseller Partners:

October 2022
  • Added support for additional Link display languages: Danish, German, Estonian, Italian, Latvian, Lithuanian, Norwegian, Polish, Romanian, and Swedish.
  • Added support for additional countries: Denmark, Estonia, Latvia, Lithuania, Poland, Norway, and Sweden.
  • Added support for USER_INPUT_TIMEOUT as a value for force_error in the Sandbox custom user schema.

For Auth:

For Investments:

  • Added non-custodial wallet to account subtypes.
  • Added trade investment transaction subtype as a subtype of transfer investment transaction type

For Income:

  • To improve reliability and developer ease of use, modified the multi-Item Link flow for Bank Income to use the new /credit/sessions/get endpoint rather than relying on Link events.
  • Added Bank Income status USER_REPORTED_NO_INCOME.
  • Added Income support to /sandbox/public_token/create.
  • Deprecated VERIFICATION_STATUS_PENDING_APPROVAL.
  • Established a 128 character limit for the client_user_id field in the /user/create request.
  • Added institution_name and institution_id fields to /credit/payroll_income/get response.

For Virtual Accounts:

  • Added options.start_time and options.end_time to /wallet/transaction/list request.
  • Added last_status_update and payment_id field to wallet transactions.

For Payment Initiation:

  • Added transaction_id field to the payment object.

For Transfer (beta):

  • Added support for RTP networks
  • Added decision rationale code PAYMENT_PROFILE_LOGIN_REQUIRED and the ability to update a Payment Profile via update mode. Also added /sandbox/payment_profile/reset_login to test this new update mode flow in Sandbox.
  • To improve consistency, renamed LOGIN_REQUIRED decision rationale to ITEM_LOGIN_REQUIRED.
  • Deprecated origination_account_id from /transfer/authorization/create endpoint.
  • Added new originator_client_id field to support Third-Party Senders (TPS).

For Wallet Onboard (beta):

For Partner Resellers:

September 2022
  • Added the ability to simulate the USER_INPUT_TIMEOUT error in Sandbox.
  • Added the ability to specify account mask when using custom Sandbox users.

For Investments:

  • Added support for crypto wallet investment account subtype non-custodial wallet and crypto trade investment transaction type.
  • Made institution_price_as_of nullable.

For Transfer (beta):

  • Added support for client-side beacons. A beacon is now required when using Guarantee with web checkout flows.
  • Removed the idempotency_key from the /transfer/authorization/create response.
  • Added settled and swept_settled transfer events and event statuses.
  • Added standard_return_window and unauthorized_return_window fields to the Transfer object.

For Payment Initiation:

For Assets:

August 2022

  • Released Identity Verification and Monitor to General Availability (GA).

  • Added issuing_region as a field in the extracted data for Identity Verification documents

  • Extended support for Android Link SDK versions prior to 3.5.0, iOS Link SDK versions prior to 2.2.2, and Link React Native SDK versions prior to 7.1.1. Previously, these SDK versions had been scheduled to be sunset on November 1, 2022. The sunset has been canceled and Plaid will now continue to support these versions past November 2022. We still recommend you use the latest SDK versions.

For Payment Initiation:

  • Added support for virtual accounts.
  • Added support for additional currencies PLN, SEK, DKK, NOK, CHF, and CZK.
  • Added PAYMENT_STATUS_SETTLED payment status.

For Income:

July 2022

For /link/token/create user object:

  • Deprecated the unused fields ssn, date_of_birth, and legal_name.
  • Added the name, address, and id_number parameters to support Identity Verification.

For Payment Initiation:

For Income:

For Transfer:

June 2022

For Auth:

  • Launched Auth Type Select (formerly known in beta as Flexible Auth or Flex Auth) to all customers. Auth Type Select allows you to optionally route end users directly to micro-deposit-based verification, even if they are eligible for Instant Match or Instant Auth.

For Transfer:

  • Made Plaid Guarantee available in beta. Guarantee allows you to guarantee the settlement of an ACH transaction, protecting you against fraud and clawbacks.
  • Added TRANSFER_LIMIT_REACHED to Transfer authorization decision rationale codes.

For Income:

For Payment Initiation (UK and Europe only):

  • Launched payment consents, which can be used to initiate payments on behalf of the user.
May 2022
  • Added Identity Verification and Monitor products in Early Access. Identity Verification checks the identity of users against identity databases and user-submitted ID documents, while Monitor checks user identities against government watchlists.

For Transactions:

For Income:

  • Added employee_type and last_paystub_date to /credit/employment/get response.
  • Removed uploaded, created and APPROVAL_STATUS_APPROVED enum strings, as these are no longer used.
April 2022

  • Added the ability to default Link to highlighting a specific institution when launching Link, via the institution_data request field.

  • Launched Income to general availability. Income allows you to verify the income of end users for purposes of loan underwriting. Various updates were also made to Income interfaces prior to launch; Income beta customers have been contacted by their account managers with details on the differences between the beta API and the released API.

For Transactions:

  • Added /transactions/recurring/get, which provides information about recurring transaction streams that can be used to help your users better manage cash flow, reduce spending, and stay on track with bill payments. This endpoint is not included by default as part of Transactions; to request access to this endpoint and learn more about pricing, contact your Plaid account manager.

For Auth:

  • Added Highnote as a processor partner. For a full list of all Auth processor partners, see Auth Payment Partners.
March 2022
  • Introduced the Institution Select shortcut, which enables you to highlight a matching institution on the Institution Select pane.
  • Added institution_data request field to /link/token/create endpoint, which accepts routing_number.
  • Added match_reason to metadata field for MATCHED_SELECT_INSTITUTION, which indicates whether routing_number or returning_user resulted in a matched institution.
  • Added support for AUTH_UPDATE and DEFAULT_UPDATE webhooks to /sandbox/item/fire_webhook. Also added webhook_type parameter to this endpoint to support different DEFAULT_UPDATE webhooks for Transactions, Liabilities, and Investments.

For Income:

  • New set of API endpoints added and numerous updates made for General Availability release. Existing beta endpoints are still supported but marked as deprecated. For more details, see the Income docs and Income API reference.

For Auth:

  • Added Apex Clearing, Checkout.com, Marqeta, and Solid as processor partners.

For Payment Initiation:

  • Added support for the IT country code.
  • Added support for searching by consent_id to /institutions/search.

For Bank Transfer (beta):

For Transfer (beta):

February 2022
  • For Transactions, released new personal finance categories to provide more intuitive and usable transaction categorization. Personal finance categories can now be accessed by calling /transactions/get with the include_personal_finance_category option enabled.
  • For Income, removed several unused fields and endpoints, including removing income_verification_id from /sandbox/income/fire_webhook and removing the /income/verification/summary/get and /income/verification/paystub/get endpoints.

For Transfer (beta):

  • Deprecated the idempotency_key parameter, as idempotency is now tracked via other identifiers.
  • Made repayment_id a required parameter for /transfer/repayment/return/list.
  • Made guaranteed fields required in Transfer endpoints.
January 2022
  • Added the ability to test the NEW_ACCOUNTS_AVAILABLE webhook via /sandbox/item/fire_webhook.
  • Updated /item/webhook/update to accept empty or null webhook URLs.
  • Updated institutions endpoints to accept null values as input for optional input fields.

For Transfer (beta):

  • Added publicly documented sweep endpoints to provide visibility into the status of Transfer sweeps.
  • Added iso_currency_code throughout the API to future-proof for multi-currency support (currently only USD is supported).
  • Made repayment_id required in /transfer/repayment/return/list endpoint

For Bank Transfer (beta):

  • Removed receiver_pending and receiver_posted from bank transfer event types, and removed receiver details from events.

For Payment Initiation:

For Income:

December 2021
  • For Transfer, updated the schema definitions for /transfer/intent/get and /transfer/intent/create.
  • For Income, deprecated the status VERIFICATION_STATUS_DOCUMENT_REJECTED.
  • For Payment Initiation, added several new statuses, including PAYMENT_STATUS_REJECTED.
November 2021
  • For Payment Initiation, added the new status PAYMENT_STATUS_EXECUTED and renamed emi_account_id to wallet_id.
  • For /asset_report/get, added the fields merchant_name and check_number to the Transactions schema, to match the Transactions schema already being used by the Transactions API.
  • For Income, added the new status VERIFICATION_STATUS_PENDING_APPROVAL.
October 2021

Multiple changes to the Income API:

Other changes:

  • For institutions endpoints, marked the status enum as deprecated in favor of the more detailed breakdown object.
  • Added DE as a supported country to support Payment Initiation use cases.
September 2021
August 2021
July 2021
  • Added new webhook for Deposit Switch.
  • Added optional country_code and options parameters to deposit switch creation endpoints, as well as new values for the state enum in the response.
  • For Deposit Switch, added additional response fields employer_name, employer_id, institution_name, institution_id, and switch_method.
  • Updated the list of ACH partners, including adding Alpaca, Astra, and Moov.
  • For /transactions/get, added the fields include_original_description and original_description in the request and response, respectively.
June 2021
  • Chase now supports real-time payments and same-day ACH for OAuth-based connections.
  • Added new Investment account subtypes life insurance, other annuity, and other insurance.
  • Added new error codes INSTITUTION_NOT_ENABLED_IN_ENVIRONMENT, INSTITUTION_NOT_FOUND, and PRODUCT_NOT_ENABLED. These codes replace more generic errors that could appear when working with OAuth institutions or API-based institution connections.
  • Began rolling out improvements to reduce balance latency.
  • Released a new representation of cryptocurrency, to represent crypto holdings more similarly to investments, rather than foreign currency, in order to match how most popular institutions represent crypto. institution_price will now reflect the USD price of the currency, as reported by the institution, and institution_value will reflect the value of the holding in USD. close_price and close_price_as_of will now be populated. iso_currency_code will be set to USD and unofficial_currency_code will be set to null.
May 2021
  • Improved the UI for Instant Match and enabled it for all "Pay as you go" customers. Customers with a monthly contract who would like to use Instant Match should contact their Plaid Account Manager.
  • Removed the requirement to be enabled by Support in order to request an Asset Report with Insights.
  • For the Payment Initiation product, launched Modular Link, allowing further UI customization.
  • For the Payment Initiation product, added an options object to /payment_initiation/payment/create to support restricting payments originating from specific accounts.
  • For the Liabilities product, added a DEFAULT_UPDATE webhook to indicate changes to liabilities accounts.
  • Made Item Debugger and improved Institution Status available to 100% of developers.
  • Added Link Consent pane customization.
  • Added the ability to use wildcards to specify a subdomain in an OAuth redirect URI.
  • Clarified that the following Link onEvent callbacks are stable: OPEN, EXIT, HANDOFF, SELECT_INSTITUTION, ERROR, but the remaining are informational.
April 2021
  • In order to support the beta generated client libraries, added the ability to provide client_id and secret via headers instead of as request parameters.
  • Added the min_last_updated_datetime parameter to /accounts/balance/get to handle institutions that do not always provide real-time balances, and added the corresponding LAST_UPDATED_DATETIME_OUT_OF_RANGE error.
  • Removed last_statement_balance from the official documentation for /liabilities/get, as it was not ever returned.
  • Fixed the case of submitting an invalid client ID to return an INVALID_API_KEYS error instead of an INTERNAL_SERVER_ERROR, in order to match documented behavior.
March 2021
  • Launched Plaid Income (beta) for verifying income and employment.
  • Added the ability to specify an end_date for standing orders in the Payment Initiation product.
  • Updated list of active processor partners.
  • Added webhook to notify of new Bank Transfers events.
  • Added /sandbox/bank_transfer/fire_webhook endpoint to test Bank Transfers webhooks.
  • Added auth_flow parameter to /link/token/create to support Flexible Auth (beta).
  • Updated the /payment_initiation/recipient/create endpoint to accept address.country_code (preferred) instead of address.country (accepted, but deprecated).
  • Removed the MATCHED_INSTITUTION_SELECT transition view event, after consolidating the returning user institution select view.
  • Added the SELECT_BRAND onEvent callback, after shipping a change that groups institution login portals within the same institution brand.
  • Stopped sending IS_MATCHED_USER and IS_MATCHED_USER_UI because these events are duplicates. You should use MATCHED_CONSENT and MATCHED_SELECT_INSTITUTION to identify when a returning user is recognized and chooses an institution that we pre-matched.
February 2021
  • Added additional payment error codes.
  • Added the UK-only fields authorized_datetime and datetime fields to the transaction object, for more detailed information on when the transaction occurred.
  • Added update_type field to the item object. This field will be used to support upcoming connectivity improvements to accounts with multi-factor authentication.
  • Added optional ssn and date_of_birth fields to the user object in /link/token/create to support upcoming functionality enhancements.
  • Released an OpenAPI file describing the Plaid API.
January 2021
  • Launched Deposit Switch (beta) for transferring direct deposits from one account to another.
  • Improved error handling to treat some invalid input errors that were previously treated as 500 errors as INVALID_INPUT errors instead.
December 2020
  • Made Bank Transfers (beta) available for testing in the Development environment.
  • Added investments_updates to the status object returned by Institutions endpoints.
November 2020
  • Removed some internal-only, pre-beta products from appearing in the /institutions/get_by_id response.
  • Restored the /item/public_token/create and /payment_initiation/payment/token/create endpoints to API version 2020-09-14 to avoid disrupting update mode for end users on older mobile SDKs that do not support Link tokens. These endpoints are still deprecated, and it is recommended you update mobile apps to the latest SDKs as soon as possible.
October 2020
  • Released API version 2020-09-14. See the version changelog for details.
  • Added support for mortgages to /liabilities/get.
  • Released Bank Transfers to closed beta.
  • To improve consistency with other error types, changed the error type for Bank Transfers errors from BANK_TRANSFER to BANK_TRANSFER_ERROR.
  • Added the fields user.phone_number, user_email.address, user.phone_number_verified_time and user.email_address_verified_time to /link/token/create to support the new Returning User Experience, which allows users a more seamless Link flow.
August 2020
  • Introduced standing orders to Payment Initiation for our UK and Europe customers. If applicable, your users will now be able to make recurring scheduled payments with a single authorization.
  • Expanded access to full Auth coverage to more developers. If you would like to use micro-deposit based verification and don't have access to it, contact your Plaid Account Manager.
  • Updated Link error messages to provide more actionable instructions for end users, making resolution troubleshooting easier.
  • Made account filtering available across all our products, so you can configure the Link flow to guide end users in selecting relevant institutions and accounts.
July 2020

  • Added the ITEM: USER_PERMISSION_REVOKED webhook, which will notify you when a user contacts Plaid directly to delete their data or change their data sharing preferences with your app.

  • Released Link tokens, the new preferred way to use Link, replacing the public key. To learn how to migrate your application to use Link tokens, see the Link token migration guide.

June 2020
  • Added a new merchant_name field to the /transactions/get endpoint for the US and Canada, providing clearer and more consistent merchant names for 95% of existing transactions.
  • Added the PAYMENT_INITIATION:PAYMENT_STATUS_UPDATE webhook, which pushes instant notifications when payment status changes for the UK Payment Initiation product.
  • Added the ability to create payment recipients via sort codes and account numbers, not just IBANs.
May 2020
  • We launched a new open finance platform called Plaid Exchange that enables financial institutions to build a consumer-permissioned data access strategy and strengthen the ability of end users to reliably access their financial data.
April 2020
  • Launched Payment Initiation in the UK, which offers an easy way for users to fund their accounts, make purchases, and pay invoices—all from their favorite apps or websites.
March 2020
  • Added the ability to filter by account_subtype, allowing you to further optimize the Link flow.
  • Added the HOLDINGS: DEFAULT_UPDATE and INVESTMENT_TRANSACTIONS: DEFAULT_UPDATE webhooks, which will fire each time data has successfully refreshed for Holdings and Investments Transactions.
February 2020
January 2020
  • Added store_number, authorized_date, and payment_channel to the /transactions/get response.
  • Added the investment_transactions.subtypes field to provide more granular detail about the tax, performance, and fee impact of investments transactions.
November 2019
  • Added the status.investments.last_successful_update and status.investments.last_failed_update fields to the data returned by /item/get.
  • Launched official support for Link on React Native with a new SDK, bringing unified support to React Native apps.
October 2019
  • Added the status.item_logins.breakdown data to /institutions/get_by_id and the Developer Dashboard.
  • Added the routing_numbers field to the Institutions object. You can also filter institutions via the options.routing_numbers field in each Institutions API endpoint.
September 2019
  • Added support for credit card details to the Liabilities product.
  • Added Canada-specific account subtypes, including RRSP, RESP, and TFSA, to the Investments product.
August 2019
  • Among numerous other improvements to Liabilities, such as expanded data access, added a new loan_type: cancelled to the Liabilities product.
July 2019
  • We launched Liabilities, which enables developers to access a feed of standardized student loan details from the largest U.S. servicers including Navient, Nelnet, FedLoan, Great Lakes, and many more.
June 2019
  • Launched Investments, which allows developers, fintech apps, and financial institutions to create a holistic view of their customers’ investments.
  • Added the status.transactions_updates field, exposing Transactions health to both the /institutions/get endpoint and the Dashboard.
May 2019
March 2019
  • We updated the institutions endpoints so you can now retrieve bank logos, colors, and website URLs to use to customize your in-app experience.
  • We enabled triggering and testing of webhooks on demand via the new /sandbox/item/fire_webhook endpoint.
February 2019
  • We launched new features for Auth, enabling developers to authenticate accounts from any bank or credit union in the U.S. Link automatically guides end-users to the best way to authenticate their account based on the bank they select.
November 2018
  • Added a new Insights feature, which provides cleaned and categorized transaction data in an Asset Report. In addition to transaction categories, lenders will be able to retrieve merchant names and locations for transactions to use in building risk models.
  • Improved the Link experience by informing users about connectivity issues with banks before connecting their account. When banks are experiencing significant issues, users will temporarily be directed to connect their account at a different bank to reduce frustration and drop-off during the onboarding process.
September 2018
  • We added the /asset_report/refresh endpoint, so you can create a new Asset Report with the latest account balances and transactions for a borrower, based on the old report.
August 2018
  • We added account filtering, which gives you the ability to exclude unnecessary accounts from appearing in an Asset Report.
June 2018
  • Added historical account balances to the PDF version of Asset Reports, bringing them closer in line with the core JSON endpoint.
May 2018
April 2018
March 2018
  • Rolled out several Assets features, including webhooks for Asset Report generation and full support for Audit Copy token generation and Fannie Mae’s Day 1 Certainty™ program, while improving existing features like pending transaction support in PDF reports.
February 2018
  • Released Assets as a beta product.

link ios

Link iOS SDK

Reference for integrating with the Link iOS SDK

To maintain support for Chase OAuth flows, all integrations must upgrade to version 4.1.0 or later of the Link iOS SDK (released January 2023) by September 30, 2023. If you are using version 2.x.x. or 3.x.x of the SDK, the only migration step required is to use XCode 14. For more details, see the in-process webview deprecation notice.

Overview

The Plaid Link SDK is a quick and secure way to link bank accounts to Plaid from within your iOS app. LinkKit is a drop-in framework that handles connecting a financial institution to your app (credential validation, multi-factor authentication, error handling, etc.) without passing sensitive information to your server.

To get started with Plaid Link for iOS, clone the GitHub repository and try out the example application, which provides a reference implementation in both Swift and Objective-C. Youʼll want to sign up for free API keys through the Plaid Developer Dashboard to get started.

Examples of Plaid Link for iOS

Initial iOS setup

Before writing code using the SDK, you must first perform some setup steps to register your app with Plaid and configure your project.

The "Register your redirect URI" and "Set up Universal Links" steps describe setting up your app for OAuth redirects. If your integration uses only Identity Verification or Monitor, they can be skipped; they are mandatory otherwise.

Register your redirect URI
  1. Sign in to the Plaid Dashboard and go to the Team Settings -> API page.
  2. Next to Allowed redirect URIs click Configure then Add New URI.
  3. Enter your redirect URI, which you must also set up as a Universal Link for your application, for example: https://app.example.com/plaid/.
  4. Click Save Changes.

These redirect URIs must be set up as Universal Links in your application. For details, see Apple's documentation on Allowing Apps and Websites to Link to Your Content.

Plaid does not support registering URLs with custom URL schemes as redirect URIs since they lack the security of Universal Links through the two-way association between your app and your website. Any application can register custom URL schemes and there is no further validation from iOS. If multiple applications have registered the same custom URL scheme, a different application may be launched each time the URL is opened. To complete Plaid OAuth flows, it is important that your application is opened and not any arbitrary application that has registered the same URL scheme.

Set up Universal Links

In order for Plaid to return control back to your application after a user completes a bank's OAuth flow, you must specify a redirect URI, which will be the URI from which Link will be re-launched to complete the OAuth flow. The redirect URI must be a Universal Link. An example of a typical redirect URI is: https://app.example.com/plaid.

Universal Links consist of the following parts:

There are a few requirements for apple-app-site-association files:

  • Must be a static JSON file
  • Must be hosted using a https:// scheme with a valid certificate and no redirects
  • Must be hosted at https://<my-fully-qualified-domain>/.well-known/apple-app-site-association

Below is an example for https://my-app.com (https://my-app.com/.well-known/apple-app-site-association)

1{
2 "applinks": {
3     "details": [
4          {
5            "appIDs": [ "<My Application Identifier Prefix>.<My Bundle ID>" ],
6            "components": [
7              {
8                 "/": "/plaid/*",
9                 "comment": "Matches any URL path whose path starts with /plaid/"
10              }
11            ]
12          }
13      ]
14  }
15}

Once you have enabled Universal Links, your iOS app is now set up and ready to start integrating with the Plaid SDK.

Ensure that the corresponding entry for the configured redirect URI in the apple-app-site-association file on your website continues to be available. If it is removed, OAuth sessions will fail until it is available again.

Installation

Plaid Link for iOS is an embeddable framework that is bundled and distributed with your application. There are several ways to obtain the necessary files and keep them up-to-date; we recommend using Swift Package Manager or CocoaPods. Regardless of what you choose, submitting a new version of your application with the updated LinkKit.xcframework to the App Store is required.

Requirements
LinkKit iOS versionXcode toolchain minimum supportSupported iOS versions
LinkKit 4.x.xXcode 14iOS 11 or greater
LinkKit 3.x.xXcode 13iOS 11 or greater
LinkKit 1.0.0 - 2.5.1Xcode 11.5iOS 11 or greater
Select group for content switcher
Swift Package Manager
  1. To integrate LinkKit using Swift Package Manager, Swift version >= 5.3 is required.
  2. In your Xcode project from the Project Navigator (Xcode ❯ View ❯ Navigators ❯ Project ⌘ 1) select your project, activate the Package Dependencies tab and click on the plus symbol ➕ to open the Add Package popup window:
  3. Enter the LinkKit package URL https://github.com/plaid/plaid-link-ios into the search bar in the top right corner of the Add Package popup window.
  4. Select the plaid-link-ios package.
  5. Choose your Dependency Rule (we recommend Up to Next Major Version).
  6. Select the project to which you would like to add LinkKit, then click Add Package:
  7. Select the LinkKit package product and click Add Package:
  8. Verify that the LinkKit Swift package was properly added as a package dependency to your project:
  9. Select your application target and ensure that the LinkKit library is embedded into your application:
Camera Support (Identity Verification only)

When using the Identity Verification product, the Link SDK may use the camera if a user needs to take a picture of identity documentation. To support this workflow, add a NSCameraUsageDescription entry to your application's plist with an informative string. This allows iOS to prompt the user for camera access. iOS will crash your application if this string is not provided.

Upgrading

New versions of LinkKit.xcframework are released frequently, at least once every few months. We recommend you keep up to date to provide the best Plaid Link experience in your application.

For details on each release see the GitHub releases and version release notes. To upgrade Plaid Link iOS from 1.x to 2.x, refer to the iOS 1.x to 2.x migration guide.

Opening Link

Before you can open Link, you need to first create a link_token. A link_token can be configured for different Link flows and is used to control much of Link’s behavior. To learn how to create a new link_token, see the API Reference entry for /link/token/create.

For iOS the /link/token/create call must include the redirect_uri parameter and it must match the redirect URI you have configured with Plaid (see Register your redirect URI above).

Create a Configuration

Starting the Plaid Link for iOS experience begins with creating a link_token. Once the link_token is passed to your app, create an instance of LinkTokenConfiguration, then create a Handler using Plaid.create() passing the previously created LinkTokenConfiguration, and call open() on the handler passing your preferred presentation method. Note that each time you open Link, you will need to get a new link_token from your server and create a new LinkTokenConfiguration with it.

create
token
String
Specify a link_token to authenticate your app with Link. This is a short lived, one-time use token that should be unique for each Link session. In addition to the primary flow, a link_token can be configured to launch Link in update mode. See the /link/token/create endpoint for more details.
onSuccess
closure
A required closure that is called when a user successfully links an Item. The closure should expect a single LinkSuccess argument, containing the publicToken String and a metadata of type SuccessMetadata. See onSuccess below.
onExit
closure
An optional closure that is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The closure should expect a single LinkExit argument, containing an optional error and a metadata of type ExitMetadata. See onExit below.
onEvent
closure
An optional closure that is called when a user reaches certain points in the Link flow. The closure should expect a single LinkEvent argument, containing an eventName enum of type EventType and a metadata of type EventMetadata. See onEvent below.
Select Language
1var linkConfiguration = LinkTokenConfiguration(
2    token: "<#LINK_TOKEN_FROM_SERVER#>",
3    onSuccess: { linkSuccess in
4        // Send the linkSuccess.publicToken to your app server.
5    }
6)
Create a Handler

A Handler is a one-time use object used to open a Link session. The Handler must be retained for the duration of the Plaid SDK flow. It will also be needed to respond to OAuth Universal Link redirects. For more details, see the OAuth guide.

Select Language
1let result = Plaid.create(configuration)
2switch result {
3  case .failure(let error):
4      logger.error("Unable to create Plaid handler due to: \(error)")
5  case .success(let handler):
6      self.handler = handler
7}
Open Link

Finally, open Link by calling open on the Handler object. This will usually be done in a button’s target action.

Select Language
1let method: PresentationMethod = .viewController(self)
2handler.open(presentUsing: method)

onSuccess

The closure is called when a user successfully links an Item. It should take a single LinkSuccess argument, containing the publicToken String and a metadata of type SuccessMetadata.

onSuccess
linkSuccess
LinkSuccess
Contains the publicToken and metadata for this successful flow.
publicToken
String
Displayed once a user has successfully linked their Item.
metadata
LinkSuccess
Displayed once a user has successfully linked their Item.
institution
nullableInstitution
An institution object. If the Item was created via Same-Day micro-deposit verification, will be null.
name
String
The full institution name, such as 'Wells Fargo'
institutionID
InstitutionID (String)
The Plaid institution identifier
accounts
Array<Account>
A list of accounts attached to the connected Item
id
AccountID (String)
The Plaid account_id
name
String
The official account name
mask
Optional<AccountMask> (Optional<String>)
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, it may also not match the mask that the bank displays to the user.
subtype
AccountSubtype
The account subtype and its type. See Account Types for a full list of possible values.
verificationStatus
Optional<VerificationStatus>
The Item's micro-deposit-based verification status. Possible values are:
pending_automatic_verification: The Item is pending automatic verification.
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the two amounts.
automatically_verified: The Item has successfully been automatically verified.
manually_verified: The Item has successfully been manually verified.
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.
nil: Micro-deposit-based verification is not being used for the Item.
linkSessionID
String
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
metadataJSON
String
Unprocessed metadata, formatted as JSON, sent from the Plaid API.
Select Language
1onSuccess: { linkSuccess in
2  // Send the linkSuccess.publicToken to your app server.
3}

onExit

This optional closure is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. It should take a single LinkExit argument, containing an optional error and a metadata of type ExitMetadata.

onExit
linkExit
LinkExit
Contains the optional error and metadata for when the flow was exited.
error
Optional<ExitError> (Swift), Optional<NSError> (Objective-C)
An Error type that contains the errorCode, errorMessage, and displayMessage of the error that was last encountered by the user. If no error was encountered, error will be nil. In Objective-C, field names will match the NSError type.
errorCode
ExitErrorCode
The error code and error type that the user encountered. Each errorCode has an associated errorType, which is a broad categorization of the error.
errorMessage
String
A developer-friendly representation of the error code.
displayMessage
Optional<String>
A user-friendly representation of the error code or nil if the error is not related to user action. This may change over time and is not safe for programmatic use.
metadata
ExitMetadata
Displayed once a user has successfully linked their Item.
status
Optional<ExitStatus>
The status key indicates the point at which the user exited the Link flow.
requiresQuestions
User prompted to answer security question(s).
requiresSelections
User prompted to answer multiple choice question(s).
requiresCode
User prompted to provide a one-time passcode.
chooseDevice
User prompted to select a device on which to receive a one-time passcode.
requiresCredentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution.
requiresAccountSelection
User prompted to select one or more financial accounts to share
institutionNotFound
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
unknown
The exit status has not been defined in the current version of the SDK. The unknown case has an associated value carrying the original exit status as sent by the Plaid API.
institution
Optional<Institution>
An institution object. If the Item was created via Same-Day micro-deposit verification, will be omitted.
institutionID
InstitutionID (String)
The Plaid specific identifier for the institution.
name
String
The full institution name, such as 'Wells Fargo'.
linkSessionID
Optional<String>
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
requestID
Optional<String>
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation.
metadataJSON
RawJSONMetadata (String)
Unprocessed metadata, formatted as JSON, sent from Plaid API.
Select Language
1linkConfiguration.onExit = { linkExit in
2  // Optionally handle linkExit data according to your application's needs
3}

onEvent

This optional closure is called when certain events in the Plaid Link flow have occurred, for example, when the user selected an institution. This enables your application to gain further insight into what is going on as the user goes through the Plaid Link flow.
The following onEvent callbacks are stable, which means that they will not be deprecated or changed: open, exit, handoff, selectInstitution, error, bankIncomeInsightsCompleted, identityVerificationPassSession, identityVerificationFailSession. The remaining callback events are informational and subject to change.

onEvent
linkEvent
LinkEvent
Contains the eventName and metadata for the Link event.
eventName
EventName
An enum representing the event that has just occurred in the Link flow.
bankIncomeInsightsCompleted
The user has completed the Assets and Bank Income Insights flow.
closeOAuth
The user closed the third-party website or mobile app without completing the OAuth flow.
error
A recoverable error occurred in the Link flow, see the errorCode in the `metadata.
exit
The user has exited without completing the Link flow and the onExit callback is fired.
failOAuth
The user encountered an error while completing the third-party's OAuth login flow.
handoff
The user has exited Link after successfully linking an Item.
identityVerificationStartStep
The user has started a step of the Identity Verification flow. The step is indicated by view_name.
identityVerificationPassStep
The user has passed a step of the Identity Verification flow. The step is indicated by view_name.
identityVerificationFailStep
The user has failed a step of the Identity Verification flow. The step is indicated by view_name.
identityVerificationReviewStep
The user has reached the pending review state.
identityVerificationCreateSession
The user has started a new Identity Verification session.
identityVerificationResumeSession
The user has resumed an existing Identity Verification session.
identityVerificationPassSession
The user has successfully completed their Identity Verification session.
identityVerificationFailSession
The user has failed their Identity Verification session.
identityVerificationPendingReviewSession
The user has completed their Identity Verification session, which is now in a pending review state.
identityVerificationOpenUI
The user has opened the UI of their Identity Verification session.
identityVerificationResumeUI
The user has resumed the UI of their Identity Verification session.
identityVerificationCloseUI
The user has closed the UI of their Identity Verification session.
matchedSelectInstitution
The user selected an institution that was presented as a matched institution. This event can be emitted either during the Returning User Experience flow or if the institution's routing_number was provided when calling /link/token/create. To distinguish between the two scenarios, see metadata.matchReason.
matchedSelectVerifyMethod
The user selected a verification method for a matched institution. This event is emitted only during the Returning User Experience flow.
open
The user has opened Link.
openMyPlaid
The user has opened my.plaid.com. This event is only sent when Link is initialized with Assets as a product.
openOAuth
The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.
searchInstitution
The user has searched for an institution.
selectBrand
The user selected a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.
selectInstitution
The user selected an institution.
submitCredentials
The user has submitted credentials.
submitMFA
The user has submitted MFA.
transitionView
The transitionView event indicates that the user has moved from one view to the next.
viewDataTypes
The user has viewed data types on the data transparency consent pane.
unknown
The event has not been defined in the current version of the SDK. The unknown case has an associated value carrying the original event name as sent by the Plaid API.
metadata
EventMetadata struct
An object containing information about the event
accountNumberMask
Optional<String>
The account number mask extracted from the user-provided account number. If the user-inputted account number is four digits long, account_number_mask is empty. Emitted by SUBMIT_ACCOUNT_NUMBER.
errorCode
Optional<ExitErrorCode>
The error code that the user encountered. Emitted by: error, exit.
errorMessage
Optional<String>
The error message that the user encountered. Emitted by: error, exit.
exitStatus
Optional<ExitStatus>
The status key indicates the point at which the user exited the Link flow. Emitted by: exit.
requiresQuestions
User prompted to answer security question(s).
requiresSelections
User prompted to answer multiple choice question(s).
requiresCode
User prompted to provide a one-time passcode.
chooseDevice
User prompted to select a device on which to receive a one-time passcode.
requiresCredentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution.
institutionNotFound
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
unknown
The exit status has not been defined in the current version of the SDK. The unknown case has an associated value carrying the original exit status as sent by the Plaid API.
institutionID
Optional<InstitutionID> (Optional<String>)
The ID of the selected institution. Emitted by: all events.
institutionName
Optional<String>
The name of the selected institution. Emitted by: all events.
institutionSearchQuery
Optional<String>
The query used to search for institutions. Emitted by: searchInstitution.
isUpdateMode
Optional<String>
Indicates if the current Link session is an update mode session. Emitted by: OPEN.
matchReason
nullablestring
The reason this institution was matched, which will be either returning_user or routing_number. Emitted by: matchedSelectInstitution.
linkSessionID
String
The link_session_id is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: all events.
mfaType
Optional<MFAType>
If set, the user has encountered one of the following MFA types: code, device, questions, selections. Emitted by: submitMFA and transitionView when viewName is mfa
requestID
Optional<String>
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
routingNumber
Optional<String>
The routing number submitted by user at the micro-deposits routing number pane. Emitted by SUBMIT_ROUTING_NUMBER.
selection
Optional<String>
Either the verification method for a matched institution selected by the user or the Auth Type Select flow type selected by the user. If selection is used to describe selected verification method, then possible values are phoneotp or password; if selection is used to describe the selected Auth Type Select flow, then possible values are flow_type_manual or flow_type_instant. Emitted by: MATCHED_SELECT_VERIFY_METHOD and SELECT_AUTH_TYPE.
timestamp
Date
An ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z. Emitted by: all events.
viewName
Optional<ViewName>
The name of the view that is being transitioned to. Emitted by: transitionView.
acceptTOS
The view showing Terms of Service in the identity verification flow.
connected
The user has connected their account.
consent
We ask the user to consent to the privacy policy.
credential
Asking the user for their account credentials.
dataTransparency
We disclose the data types being shared.
dataTransparencyConsent
We ask the user to consent to the privacy policy and disclose data types being shared.
documentaryVerification
The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor).
error
An error has occurred.
exit
Confirming if the user wishes to close Link.
kycCheck
The view representing the "know your customer" step in the identity verification flow.
loading
Link is making a request to our servers.
matchedConsent
We ask the matched user to consent to the privacy policy and SMS terms.
matchedCredential
We ask the matched user for their account credentials to a matched institution.
matchedMfa
We ask the matched user for MFA authentication to verify their identity.
mfa
The user is asked by the institution for additional MFA authentication.
numbers
The user is asked to insert their account and routing numbers.
oauth
The user is informed they will authenticate with the financial institution via OAuth.
recaptcha
The user was presented with a Google reCAPTCHA to verify they are human.
riskCheck
The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor).
screening
The watchlist screening step in the identity verification flow.
selectAccount
We ask the user to choose an account.
selectAuthType
The user is asked to choose whether to Link instantly or manually (i.e., with micro-deposits).
selectBrand
The user is asked to select a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.
selectInstitution
We ask the user to choose their institution.
selfieCheck
The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.
uploadDocuments
The user is asked to upload documents (for Income verification).
verifySMS
The SMS verification step in the identity verification flow.
unknown
The view has not been defined in the current version of the SDK. The unknown case has an associated value carrying the original view name as sent by the Plaid API.
metadataJSON
RawJSONMetadata (String)
Unprocessed metadata, formatted as JSON, sent from Plaid API.
Select Language
1linkConfiguration.onEvent = { linkEvent in
2  // Optionally handle linkEvent data according to your application's needs
3}

Next steps

Once you've gotten Link working, see Link best practices for recommendations on further improving the Link flow.

auth partnerships galileo

Add Galileo to your app

Use Galileo with Plaid Auth to send and receive payments!

Partnership Galileo logo

Overview

Plaid and Galileo have partnered to provide the simplest way for your cardholders to fund their accounts on your banking platform. Your cardholders can verify their external bank accounts from Plaid's drop-in module within your app or website. Once an external account is verified, you can use Galileo to transfer money between the external account and your cardholder's account on your platform.

This integration was built with security in mind, as it eliminates the need for you to store sensitive information from your cardholders' external bank accounts.

To get started sign up for Plaid API keys.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Galileo account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Galileo processor_token, which allows you to quickly and securely verify a bank funding source via Galileo's API without having to store any sensitive banking information. Utilizing Plaid + Galileo enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Galileo in order to use the Plaid + Galileo integration. You'll also need to enable your Plaid account for the Galileo integration.

First, you will need to work with the Galileo team to sign up for a Galileo account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Galileo to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Galileo processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Galileo, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Galileo processor_token. You'll send this token to Galileo and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Galileo processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'galileo',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Galileo Production credentials prior to initiating live payment transactions in the Galileo API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

auth partnerships checkbook

Add Checkbook to your app

Use Checkbook with Plaid Auth to send and receive payments!

Partnership Checkbook logo

Overview

Plaid and Checkbook have partnered to provide a seamless way to integrate Plaid’s instant account verification with Checkbook’s digital payment solution. With Plaid Link, users can quickly and securely onboard a bank account to natively issue payments through Checkbook’s API. Checkbook's wide range of payment options -- including ACH, real-time payments, push to card, virtual cards, and checks -- enable customized payment solutions for every business need.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Checkbook account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Checkbook processor_token, which allows you to quickly and securely verify a bank funding source via Checkbook's API without having to store any sensitive banking information. Utilizing Plaid + Checkbook enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Checkbook in order to use the Plaid + Checkbook integration. You'll also need to enable your Plaid account for the Checkbook integration.

First, you will need to work with the Checkbook team to sign up for a Checkbook account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Checkbook to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Checkbook processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Checkbook, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Checkbook processor_token. You'll send this token to Checkbook and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Checkbook processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'checkbook',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Checkbook Production credentials prior to initiating live payment transactions in the Checkbook API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

signal

Introduction to Signal

Assess the return risk of an ACH debit transaction

Explore API

Overview

Plaid Signal allows you to evaluate the likelihood of a specific ACH transaction resulting in a return. Signal is powered by a machine learning model trained on Plaid’s consumer-permissioned data network, including over 1,000 risk factors, and is designed to provide a result in under one second. Signal provides two overall risk assessment scores, along with associated risk tiers and over 60 predictive insights that you can incorporate into your own risk assessment models. By using the Signal API, you can release funds earlier to optimize your user experience while managing the risk of ACH returns.

Prefer to learn by watching? Get an overview of how Signal works in just 3 minutes!

Usage

Signal is intended to be used alongside Auth.

The Signal API consists of three routes and one optional route:

/signal/evaluate: Call this endpoint before initiating an ACH transaction to get the return risk assessment and additional risk signals.

/signal/decision/report: After calling /signal/evaluate, call this endpoint to inform Plaid of your risk and payment decision outcome and whether or not you executed the ACH transaction. Your decision feedback will help the model to optimize for your use case.

/signal/return/report: Call this endpoint when you receive a return for the ACH transaction you previously called the /signal/evaluate endpoint for. Your feedback allows the model to incorporate the latest risk trends into its assessments.

/signal/prepare (optional): This endpoint is intended for customers who use Signal alongside Identity. In the specific scenario when /identity/get is called immediately after linking an Item, but the Item was not configured with Signal or Identity upon its creation, calling /signal/prepare immediately after /identity/get can reduce latency.

Sample flow

  1. Using /link/token/create, create a Link token initialized with the auth and signal products, and use this token to launch Link.
  2. The end user completes the Link flow by logging into their financial institution.
  3. Use /item/public_token/exchange to exchange the public_token returned from Link's onSuccess callback for an access_token.
  4. Call /accounts/get using the access_token returned in the previous step to obtain the account_id of the account you will be evaluating.
  5. Call /signal/evaluate using the access_token and account_id obtained in the previous steps.
  6. Based on the data returned by /signal/evaluate, decide whether to proceed directly with the transfer or apply an additional risk mitigation layer. You may either use the risk scoring and tier data returned by /signal/evaluate or use the core_attributes and feed them into your own model, along with additional information you may have about the user and the proposed transaction. For potentially high-risk transactions, you can also call /accounts/balance/get at this point to obtain real-time balance information and use it as another input into your decision.
  7. If you decide to proceed with the transfer, initiate it as you normally would using Plaid Auth endpoints. For more details, see Auth.
  8. Report your decision following the risk assessment and whether or not to proceed with the transfer by calling /signal/decision/report.
  9. If the transfer is later returned, call /signal/return/report.

Signal data

Signal provides two categories of risk -- customer-initiated return risk, which corresponds to ACH returns initiated by customers (unauthorized ACH returns), and bank-initiated return risk (primarily NSFs and administrative returns), which corresponds to ACH returns initiated by financial institutions. Each risk category has a score ranging from 1-99 and a corresponding risk tier to help you better understand the associated level of return risk.

In addition to the risk scores and tiers, Signal also provides more than 60 predictive insights to help provide even greater visibility into the factors contributing to a given score and tier. You may choose to incorporate these insights into your own risk models.

For more details on the data returned by Signal, see the Signal API reference.

1{
2  "scores": {
3    "customer_initiated_return_risk": {
4      "score": 9,
5      "risk_tier": 1
6    },
7    "bank_initiated_return_risk": {
8      "score": 72,
9      "risk_tier": 7
10    }
11  },
12  "core_attributes": {
13    "days_since_first_plaid_connection": 510,
14    "plaid_connections_count_7d": 6,
15    "plaid_connections_count_30d": 7,
16    "total_plaid_connections_count": 15,
17    "is_savings_or_money_market_account": false,
18    ...
19  },
20  "request_id": "mdqfuVxeoza6mhu"
21}

Testing Signal

You can test Signal in the Sandbox and Development environments. Note that the /sandbox/public_token/create endpoint does not allow signal in the initial_products array; for testing with this endpoint, put auth in the initial_products array instead, then proceed to call the Signal endpoints as normal.

Next steps

If you're ready to launch to Production, see the Launch checklist.

transfer reconciling transfers

Reconciling Transfers

Learn how to reconcile transfers

You can use the /transfer/event/sync endpoint to retrieve all of the events and statuses associated with your transfers. This is useful when performing reconciliation, as it guarantees that you've seen all transfer events. The main identifier for Plaid transfers is the transfer_id. You should plan to store this identifier to help facilitate transfer reconciliation.

This article describes how to programmatically track transfer events and status. If you would prefer to view this information via a graphical interface or a CSV file, see the Dashboard.

Syncing Transfer events

First, retrieve from your datastore the last event_id that was retrieved from the sync endpoint and set that as your after_id.

1after_id = yourDatabase.get("after_id")
2events = new Array(BankTransferEvent)

Next, call the /transfer/event/sync endpoint with that after_id and persist the returned events in your datastore. The endpoint will return a maximum of 25 events at a time. Continue calling the /transfer/event/sync endpoint, passing in the last event_id from the previous call until the response has zero results.

1# Start at the last event ID received
2after_id = yourDatabase.get("after_id")
3events = new Array(BankTransferEvent)
4
5# Poll event sync endpoint until there are no more new events
6do {
7  # Fetch the next set of events and update after_id
8  events = plaidClient.BankTransferEventSync(after_id)
9  after_id += len(events)
10
11  # Handle any new events
12  for event in events {
13    # Store ID, event type (e.g. pending, posted, failed, canceled), timestamp
14    yourDatabase.set(event.bank_transfer_id, event.event_type, event.timestamp}
15} while (!events.Empty());

Finally, persist that last event_id in your datastore to use the next time you perform this process.

1yourDatabase.set("after_id", after_id)

Sample app code

For a real-life example of an app that incorporates the /transfer/event/sync endpoint, see the Node-based Plaid Pattern Transfer sample app. Pattern Transfer is a sample subscriptions payment app that enables ACH bank transfers. The Transfer event sync code can be found in handleTransferWebhook.js

Progression of Transfer events

A single transfer will have more than one event associated with it. For example, a successful transfer’s status will initially start out as pending before it’s sent to the ACH network, then move to posted when the funds are available in the account. Each of these status updates will return a unique event from the /transfer/event/sync endpoint, so, in this example, you’ll see two events for this particular transfer_id throughout its lifespan.

Listed below are the event transitions you will see as a transfer progresses through its lifespan.

DescriptionEvent(s)
You submitted a transferpending
You cancelled the transferpending → cancelled
The transfer could not be processed, reach out to your Plaid point of contactpending → failed
Funds are available in your or your user’s accountpending → posted
Transfer has resulted in an ACH return and funds have been clawed backpending → posted → returned

auth partnerships lithic

Add Lithic to your app

Use Lithic with Plaid Auth to send and receive payments!

Partnership Lithic logo

Overview

Plaid and Lithic have partnered to streamline ACH payments and card loads for Lithic API Issuing customers. Use Plaid Link to instantly connect customer bank accounts to load funds or initiate ACH transfers.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Lithic account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Lithic processor_token, which allows you to quickly and securely verify a bank funding source via Lithic's API without having to store any sensitive banking information. Utilizing Plaid + Lithic enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Lithic in order to use the Plaid + Lithic integration. You'll also need to enable your Plaid account for the Lithic integration.

First, you will need to work with the Lithic team to sign up for a Lithic account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Lithic to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Lithic processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Lithic, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Lithic processor_token. You'll send this token to Lithic and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Lithic processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'lithic',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Lithic Production credentials prior to initiating live payment transactions in the Lithic API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

monitor algorithms and lists

Algorithms and Lists

Learn about the search algorithms employed by Plaid Monitor as well as the available lists.

Plaid Monitor's system supports a wide variety of algorithms and languages to support common inconsistencies across both user inputs and underlying watchlist search data.

Supported languages

ArabicGermanKorean
SpanishSimplified ChineseGreek
PashtoThaiTraditional Chinese
HungarianPersianUrdu
EnglishItalianPortuguese
FrenchJapaneseRussian
HebrewBurmeseVietnamese

Supported algorithms

Phonetic similarityJesus ↔ Heyzeus ↔ Haezoos
Transliteration spelling differencesAbdul Rasheed ↔ Abd al-Rashid
NicknamesWilliam ↔ Will ↔ Bill ↔ Billy
Missing spaces or hyphensMaryEllen ↔ Mary Ellen ↔ Mary-Ellen
Titles and honorificsDr. ↔ Mr. ↔ Ph.D.
Truncated name componentsMcDonalds ↔ McDonald ↔ McD
Missing name componentsPhillip Charles Carr ↔ Phillip Carr
Out-of-order name componentsDiaz, Carlos Alfonzo ↔ Carlos Alfonzo Diaz
InitialsJ. E. Smith ↔ James Earl Smith
Names split inconsistently across database fieldsDick. Van Dyke ↔ Dick Van . Dyke
Same name in multiple languagesMao Zedong ↔ Мао Цзэдун ↔ 毛泽东 ↔ 毛澤東
Semantically similar namesEagle Pharmaceuticals, Inc. ↔ Eagle Drugs, Co.
Semantically similar names across languageNippon Telegraph and Telephone Corporation ↔ 日本電信電話株式会社
Name sensitivity

Plaid determines a similarity score based on the result of these comparisons. Each type of matching will have a different impact on the overall similarity score, based on the importance of the discrepancy, the length and composition of the name being verified, and other variables like language. For example, "Mr. John Doe" vs. "John Doe" will receive a negligible penalty, whereas "John Paul Doe" vs "John Doe" will receive a more significant penalty.

The sensitivity you select will determine the minimum similarity score required for a match. We recommend that you start with Balanced sensitivity and adjust as needed.

If you are migrating from another identity verification solution and have configured similarity scores there, you can use the following table to roughly equate Plaid's sensitivity levels with similarity scores:

Name sensitivityMinimum acceptable similarity score
Coarse70
Balanced80
Strict90
Exact100

Note that setting the scores at a comparable level between different solutions will not yield exactly the same results, since different products use different algorithms.

Supported watchlists

US – Office of Foreign Assets Control

  • Specially Designated Nationals List
  • Foreign Sanctions Evaders
  • Palestinian Legislative Council
  • Sectoral Sanctions Identifications
  • Non-SDN Menu-Based Sanctions
  • Correspondent Account or Payable-Through Account Sanctions
  • Non-SDN Chinese Military-Industrial Complex List

US - Department of Justice

  • FBI Wanted List

US – Department of State

  • Nonproliferation Sanctions
  • AECA Debarred

Bureau of Industry and Security

  • Denied Persons List
  • Unverified List

UK – Her Majesty’s Treasury

  • Consolidated list

EU – European External Action Service

  • Consolidated list

AU – Department of Foreign Affairs and Trade

  • Consolidated list

CA – Government of Canada

  • Consolidated List of Sanctions

International

  • Interpol Red Notices for Wanted Persons List
  • World Bank Listing of Ineligible Firms and Individuals
  • United Nations Consolidated Sanctions

Politically Exposed Persons

  • Politically Exposed Persons List
  • State Owned Enterprise List
  • CIA List of Chiefs of State and Cabinet Members

SG - Government of Singapore

  • Terrorists and Terrorist Entities

TR - Government of Turkey

  • Terrorist Wanted List
  • Domestic Freezing Decisions
  • Foreign Freezing Requests
  • Weapons of Mass Destruction
  • Capital Markets Board

transactions troubleshooting

Troubleshooting Transactions

API error responses

If the problem you're encountering involves an API error message, see Errors for troubleshooting suggestions.

No transactions or cursor returned

When calling /transactions/sync, a response with no cursor or transactions data is returned.

Common causes
  • This is expected behavior when the Item has recently been initialized with transactions and Plaid has not yet completed fetching of transactions data.
Troubleshooting steps

Missing transactions

Common causes

  • The institution is experiencing an error.

  • Processing of the transactions has been delayed.

  • The Item is not in a healthy state.

  • The transaction is not available on the institution's online banking portal, or appears differently on the online banking portal.

Troubleshooting steps

If the steps above do not resolve the issue, file a ticket with Plaid support.

Incorrect data fields

In some cases, information about a merchant, such as its name or category, may be incorrect.

Troubleshooting steps

If the issue is not resolved, or if the category information is incorrect, file a ticket with Plaid support indicating which fields are incorrect, the correct data, and the transaction_id of the affected transaction.

auth partnerships bond

Add Bond to your app

Use Bond with Plaid Auth to send and receive payments!

Partnership Bond logo

Overview

Plaid and Bond have partnered to provide Bond customers a seamless and secure way to link external bank accounts to Bond. With Bond’s APIs, you can then connect the linked accounts to Bond customers or businesses and make ACH payments to and from those linked accounts.

Plaid’s SDKs make it easy to link account information across a variety of platforms. Bond provides a full suite of banking, credit, and compliance products that allows customers to onboard consumers and businesses, open deposit accounts, issue cards, and make payments in a unified API platform. Using this integration, you can leverage Plaid’s multi-platform SDKs while leaving the nuances of validating, originating, and operating ACH payments to Bond.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Bond account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Bond processor_token, which allows you to quickly and securely verify a bank funding source via Bond's API without having to store any sensitive banking information. Utilizing Plaid + Bond enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Bond in order to use the Plaid + Bond integration. You'll also need to enable your Plaid account for the Bond integration.

First, you will need to work with the Bond team to sign up for a Bond account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Bond to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Bond processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Bond, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Bond processor_token. You'll send this token to Bond and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Bond processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'bond',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Bond Production credentials prior to initiating live payment transactions in the Bond API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

errors virtual account

Virtual Account(UK/EU) Errors

TRANSACTION_INSUFFICIENT_FUNDS

Common Causes
  • The account does not have sufficient funds to complete the transaction.
1http code 400
2{
3 "error_type": "TRANSACTION_ERROR",
4 "error_code": "TRANSACTION_INSUFFICIENT_FUNDS",
5 "error_message": "Insufficient funds to complete the transaction",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

TRANSACTION_EXECUTION_FAILED

Common Causes
  • The transaction failed to execute due to an internal error.
  • The transaction might have been declined by the receiving bank.
  • Technical issues with the payment processor.
1http code 400
2{
3 "error_type": "TRANSACTION_ERROR",
4 "error_code": "TRANSACTION_EXECUTION_FAILED",
5 "error_message": "There was a problem executing the transaction. Please retry.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

NONIDENTICAL_REQUEST

Common Causes
  • The request parameters have changed compared to the original request with the same idempotency key.
1http code 400
2{
3 "error_type": "TRANSACTION_ERROR",
4 "error_code": "NONIDENTICAL_REQUEST",
5 "error_message": "Request body does not match previous request with this idempotency key",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

REQUEST_CONFLICT

Common Causes
  • The original request is still processing and has not completed.
  • A network or system issue caused a delay in processing the original request, resulting in a conflict when the new request is sent.
1http code 400
2{
3 "error_type": "TRANSACTION_ERROR",
4 "error_code": "REQUEST_CONFLICT",
5 "error_message": "Original request is still processing",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

api webhooks webhook verification

Verify webhooks

API reference for verifying webhooks

Plaid signs all outgoing webhooks so that you can verify the authenticity of any incoming webhooks to your application. A message signature is included in the Plaid-Verification header (Note: this is the canonical representation of the header field, but HTTP 1.x headers should be handled as case-insensitive, HTTP 2 headers are always lowercase). The verification process is optional and is not required for your application to handle Plaid webhooks.

The verification process requires understanding JSON Web Tokens (JWTs) and JSON Web Keys (JWKs). More information about these specifications can be found at jwt.io.

Libraries for interpreting and verifying JWKs and JWTs most likely exist in your preferred language. It is highly recommended that you utilize well-tested libraries rather than trying to implement these specifications from scratch.

Steps to verify webhooks

Extract the JWT header

Extract the Plaid-Verification HTTP header from any Plaid webhook (to get a webhook, see firing webhooks in Sandbox). The value of the Plaid-Verification header is a JWT, and will be referred to as "the JWT" in following steps.

Using your preferred JWT library, decode the JWT and extract the header without validating the signature. This functionality most likely exists in your preferred JWT library. An example JWT header is shown below.

1{
2  "alg": "ES256",
3  "kid": "bfbd5111-8e33-4643-8ced-b2e642a72f3c",
4  "typ": "JWT"
5}

Ensure that the value of the alg (algorithm) field in the header is "ES256". Reject the webhook if this is not the case.

Extract the value corresponding to the kid (key ID) field. This will be used to retrieve the JWK public key corresponding to the private key that was used to sign this request.

Get the verification key

Use the /webhook_verification_key/get endpoint to get the webhook verification key.

/webhook_verification_key/get

Get webhook verification key

Plaid signs all outgoing webhooks and provides JSON Web Tokens (JWTs) so that you can verify the authenticity of any incoming webhooks to your application. A message signature is included in the Plaid-Verification header.
The /webhook_verification_key/get endpoint provides a JSON Web Key (JWK) that can be used to verify a JWT.

webhook_verification_key/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
key_id
requiredstring
The key ID ( kid ) from the JWT header.
Select group for content switcher
Select Language
1const request: WebhookVerificationKeyGetRequest = {
2  key_id: keyID,
3};
4try {
5  const response = await plaidClient.webhookVerificationKeyGet(request);
6  const key = response.data.key;
7} catch (error) {
8  // handle error
9}
webhook_verification_key/get

Response fields and example

key
object
A JSON Web Key (JWK) that can be used in conjunction with JWT libraries to verify Plaid webhooks
alg
string
The alg member identifies the cryptographic algorithm family used with the key.
crv
string
The crv member identifies the cryptographic curve used with the key.
kid
string
The kid (Key ID) member can be used to match a specific key. This can be used, for instance, to choose among a set of keys within the JWK during key rollover.
kty
string
The kty (key type) parameter identifies the cryptographic algorithm family used with the key, such as RSA or EC.
use
string
The use (public key use) parameter identifies the intended use of the public key.
x
string
The x member contains the x coordinate for the elliptic curve point, provided as a base64url-encoded string of the coordinate's big endian representation.
y
string
The y member contains the y coordinate for the elliptic curve point, provided as a base64url-encoded string of the coordinate's big endian representation.
created_at
integer
The timestamp when the key was created, in Unix time.
expired_at
nullableinteger
The timestamp when the key expired, in Unix time.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "key": {
3    "alg": "ES256",
4    "created_at": 1560466150,
5    "crv": "P-256",
6    "expired_at": null,
7    "kid": "bfbd5111-8e33-4643-8ced-b2e642a72f3c",
8    "kty": "EC",
9    "use": "sig",
10    "x": "hKXLGIjWvCBv-cP5euCTxl8g9GLG9zHo_3pO5NN1DwQ",
11    "y": "shhexqPB7YffGn6fR6h2UhTSuCtPmfzQJ6ENVIoO4Ys"
12  },
13  "request_id": "RZ6Omi1bzzwDaLo"
14}
Was this helpful?
Validate the webhook

Interpret the returned key as a JWK public key. Using your preferred JWT library, verify the JWT using the JWK. If the signature is not valid, reject the webhook. Otherwise, extract the payload of the JWT. It will look something like the JSON below.

1{
2  "iat": 1560211755,
3  "request_body_sha256": "bbe8e9..."
4}

Use the issued at time denoted by the iat field to verify that the webhook is not more than 5 minutes old. Rejecting outdated webhooks can help prevent replay attacks.

Extract the value of the request_body_sha256 field. This will be used to check the integrity and authenticity of the webhook body.

Compute the SHA-256 of the webhook body and ensure that it matches what is specified in the request_body_sha256 field of the validated JWT. If not, reject the webhook. It is best practice to use a constant time string/hash comparison method in your preferred language to prevent timing attacks.

Note that the request_body_sha256 sent in the JWT payload is sensitive to the whitespace in the webhook body and uses a tab-spacing of 2. If the webhook body is stored with a tab-spacing of 4, the hash will not match.

Caching and key rotation

It is recommended that your application caches the public key for a given key ID, but for no more than 24 hours. This reduces the likelihood of using an expired key to validate incoming webhooks.

It may be possible that a key rotation will take place. If your application encounters a webhook with a key ID that it does not have in its cache, it should make an API request to fetch the associated public key. In addition, your application must refetch any keys from the API that are currently in the cache but not yet expired. This helps to ensure that expired keys are not being used for live validation of webhooks by refreshing the expired_at field.

Example implementation

The following code shows one example method that can be used to verify webhooks sent by Plaid and cache public keys.

Select Language
1const compare = require('secure-compare');
2const jwt_decode = require('jwt-decode');
3const JWT = require('jose');
4const sha256 = require('js-sha256');
5const plaid = require('plaid');
6
7// Cache for webhook validation keys.
8const KEY_CACHE = new Map();
9
10const plaidClient = new plaid.Client({
11  clientID: process.env.CLIENT_ID,
12  secret: process.env.SECRET,
13  env: plaid.environments.sandbox,
14});
15
16const verify = async (body, headers) => {
17  const signedJwt = JSON.parse(headers)['plaid-verification'];
18  const decodedToken = jwt_decode(signedJwt);
19  // Extract the JWT header
20  const decodedTokenHeader = jwt_decode(signedJwt, { header: true });
21  // Extract the kid value from the header
22  const currentKeyID = decodedTokenHeader.kid;
23
24  //If key not in cache, update the key cache
25  if (!KEY_CACHE.has(currentKeyID)) {
26    const keyIDsToUpdate = [];
27    KEY_CACHE.forEach((keyID, key) => {
28      // We will also want to refresh any not-yet-expired keys
29      if (key.expired_at == null) {
30        keyIDsToUpdate.push(keyID);
31      }
32    });
33
34    keyIDsToUpdate.push(currentKeyID);
35
36    for (const keyID of keyIDsToUpdate) {
37      const response = await plaidClient
38        .webhookVerificationKeyGet({
39          key_id: keyID,
40        })
41        .catch((err) => {
42          // decide how you want to handle unexpected API errors,
43          // e.g. retry later
44          return false;
45        });
46      const key = response.data.key;
47      KEY_CACHE.set(keyID, key);
48    }
49  }
50
51  // If the key ID is not in the cache, the key ID may be invalid.
52  if (!KEY_CACHE.has(currentKeyID)) {
53    return false;
54  }
55
56  // Fetch the current key from the cache.
57  const key = KEY_CACHE.get(currentKeyID);
58
59  // Reject expired keys.
60  if (key.expired_at != null) {
61    return false;
62  }
63
64  // Validate the signature and iat
65  try {
66    const keyLike = await JWT.importJWK(key);
67    // This will throw an error if verification fails
68    const { payload } = await JWT.jwtVerify(signedJwt, keyLike, {
69      maxTokenAge: '5 min',
70    });
71  } catch (error) {
72    return false;
73  }
74
75  // Compare hashes.
76  const bodyHash = sha256(body);
77  const claimedBodyHash = decodedToken.request_body_sha256;
78  return compare(bodyHash, claimedBodyHash);
79};

balance troubleshooting

Troubleshooting Balance

API error responses

If the problem you're encountering involves an API error message, see Errors for troubleshooting suggestions.

Inaccurate balance

Common causes
  • The /accounts/get endpoint is being used instead of /accounts/balance/get for real-time data.
  • Available balance is being reported when the user expects to see current balance, or vice-versa.
Troubleshooting steps

transfer platform payments

Platform Payments

Learn how to use Transfer as a Payments Platform

Transfer is only supported in Plaid's Sandbox and Production environments.

Overview

For Platform Payments (beta) customers, the Platform Payments APIs provide a scalable method to onboard new end customers, or Originators, onto your platform. With Plaid’s hosted onboarding UI, you can collect and send Originators' required business data to Plaid without needing to build and maintain form fields.

Platform Payments (beta) allows you to onboard your business customers and initiate ACH transfers on their behalf. To onboard your customer, you will generate a unique onboarding URL via the API and redirect them to that URL. This onboarding URL will have an application form where they can provide necessary information such as their business details and bank account. After completing this form, they will be redirected back to your website or app. Upon approval, you can create ACH transfers on their behalf by specifying their unique ID. All funds for that particular customer will be swept to or from their business checking account, which they will connect during their onboarding.

Note that Platform Payments (beta) uses a hosted onboarding UI and cannot be used with Transfer UI.

Integration process

To onboard an Originator onto your platform using Plaid’s Platform Payments and move money on their behalf:

  1. Create a new Originator by calling /transfer/originator/create, which will generate an originator_client_id.
  2. Generate a unique onboarding URL by calling /transfer/questionnaire/create and redirect the Originator to that URL to complete their application with Plaid.
  3. Retrieve onboarding status updates for an Originator by calling /transfer/originator/get or /transfer/originator/list.
  4. Create an Item (access_token) for an end user using Plaid Link, /link/token/create, and /item/public_token/exchange.
  5. Move money for an Originator by calling /transfer/authorization/create and /transfer/create and specifying the access_token and originator_client_id.
  6. (Optional) Retrieve money movement updates via /transfer/list, /transfer/event/list, or /transfer/sweep/list.
Creating a new Originator

Within your current onboarding flow for your customers (i.e. Originators), create an Originator in Plaid’s system by calling the /transfer/originator/create endpoint. This endpoint will return an originator_client_id, which you should store associated with the Originator's customer profile, since you’ll need to provide it when moving money on their behalf.

Generating a unique onboarding URL

Pass the originator_client_id and a redirect_url to the /transfer/questionnaire/create endpoint, which will return a unique URL that you should redirect the Originator to. It will take the Originator to a Plaid hosted onboarding UI where they can provide the required details and agree to the Plaid terms and conditions for ACH money movement. After clicking submit, they will be redirected back to your application via the redirect_url provided.

Retrieving onboarding status updates for an Originator

Call the /transfer/originator/get endpoint with the originator_client_id to receive the status of their onboarding or call /transfer/originator/list endpoint to receive status updates for each of your Originator’s onboarding. If Plaid requires any additional information for your Originator, we will reach out directly to them to obtain it. Once an Originator's status is approved, you can move money on behalf of that Originator.

If you qualify for delegated diligence and the Originator does not fall under Plaid’s restricted use-cases, the Originator will be instantly approved. To find out if you qualify, contact your Plaid account manager.

Creating an Item for a user

Using your own client ID (i.e. not the Originator’s client ID), create an Item (access_token) for a user using Link, /link/token/create, and /item/public_token/exchange. Note that this Item can be used to create transfers with any originator_client_id that you have onboarded.

Moving money for an Originator

Provide the originator_client_id of the Originator when calling /transfer/authorization/create to authorize the Transfer. Then, with the returned authorization_id, call /transfer/create to move the money.

Receiving money movement updates for an Originator

Provide the originator_client_id of the Originator when calling the /transfer/list, /transfer/event/list, or /transfer/sweep/list endpoints to get money movement updates.

transfer recurring transfers

Recurring Transfers

Learn how to set up and use recurring ACH transactions

Overview

Recurring transfers allow you to automatically originate fixed amount ACH transactions with a regular interval according to a schedule you define. Plaid currently supports intervals with an arbitrary number of weeks or months.

Once the recurring transfer has been set up, Plaid automatically originates the ACH transaction on the planned date, defined by the recurring schedule. You can look up and cancel recurring transfers. You may also receive updates about the recurring transfer itself, as well as each individual transfer originated by the recurring transfer.

Creating a recurring transfer

Use /transfer/recurring/create to create a new recurring transfer. The request body looks very similar to /transfer/authorization/create, except that you should provide an additional schedule parameter.

The schedule parameter defines the start date and the recurring interval. Optionally, you may provide an end date which is the last day, inclusively, that an ACH transaction can be originated. If the end date is not set, the recurring transfer remains active until being cancelled.

The recurrence interval is calculated by multiplying interval_unit by interval_count. For example, to set up a recurring transfer that’s originated once every 2 weeks, set interval_unit = "week" and interval_count = 2.

The interval_execution_day parameter indicates which day in the week or month that you expect a new ACH transaction to be originated.

  • For a weekly recurring schedule, interval_execution_day should be an integer ranging from 1 to 5, representing Monday through Friday.
  • For a monthly recurring schedule, interval_execution_day should be either
    • a positive integer ranging from 1 to 28, indicating the 1st through 28th day of the month;
    • or a negative integer ranging from -1 to -5, where -1 is the last day of the month, -2 is the second-to-last day of the month, and so on.

Cancelling a recurring transfer

To cancel a recurring transfer, use /transfer/recurring/cancel and provide the id of the recurring transfer you wish to cancel.

If you cancel a recurring transfer on the same day that a new ACH transaction is supposed to be originated, it is not guaranteed that this transaction can be cancelled.

Weekend and bank holiday adjustment

If the planned origination date falls on a weekend or a bank holiday, Plaid automatically adjusts it to the next available banking day, provided that the adjusted date is on or before the schedule’s end_date.

This means if the origination date after adjustment falls after the recurring schedule’s end_date, it will not be originated. We recommend you always choose a banking day as the end_date in the schedule if it’s needed.

Examples of recurring schedule
  • Originate once every month on the 5th day, starting from 2022-08-01, with no end date:
    • interval_unit = "month"; interval_count = 1; interval_execution_day = 5; start_date = "2022-08-01".
  • Originate once every 3 months on the last day of the month for 9 months, starting from 2022-07-31:
    • interval_unit = "month"; interval_count = 3; interval_execution_day = -1; start_date = "2022-07-30"; end_date = "2023-05-01". Note that because 2023-04-30 is a Saturday, we set end_date to 2023-05-01, which is the following bank working day.
  • Originate once every 4 weeks on Tuesday, with no end date, starting from 2022-08-01:
    • interval_unit = "week"; interval_count = 4; interval_execution_day = 2; start_date = "2022-08-01".

Receiving updates of a recurring transfer

Plaid sends following webhook events regarding a recurring transfer:

  • RECURRING_NEW_TRANSFER when a new ACH transaction is originated on the planned date.
  • RECURRING_TRANSFER_SKIPPED when Plaid is unable to originate a new ACH transaction on the planned date.
  • RECURRING_CANCELLED when the recurring transfer is cancelled by Plaid.

For all transfers created through recurring transfer, TRANSFER_EVENTS_UPDATE webhook events are also sent so that you can receive updates on each individual ACH transaction.

In addition, the transfers created through recurring transfer would appear in the response of /transfer/list, and can be queried by /transfer/get given its transfer_id. The recurring_transfer object also has a transfer_ids field, which contains the ids of the transfers originated by this recurring transfer.

Simulating recurring transfers in Sandbox

In the Sandbox environment, recurring transfers can be simulated by using a test_clock object.

A test_clock is a mock clock that has a virtual_time field, indicating the current timestamp on this test clock. You can attach a test_clock to a recurring_transfer in Sandbox by providing a test_clock_id when you call /transfer/recurring/create.

You can advance the virtual_time on a test_clock to a higher value by calling /sandbox/transfer/test_clock/advance, but you can never decrease the virtual_time.

When a test clock is advanced, all active recurring transfers attached to this clock will generate new originations as if the time had elapsed in production. For instance, assuming a test clock is attached to a weekly recurring transfer, if the test clock is advanced by 14 days, you should see two new transfers being created.

Note that advancing a test clock does not change the status of the transfer objects created by a recurring transfer. Transfers will stay in pending status unless you call /sandbox/transfer/simulate to simulate a transfer status update.

Sample Sandbox recurring transfer scenarios
  1. Create a test clock using /sandbox/transfer/test_clock/create, with a virtual_time of "2022-11-14T07:00:00-08:00", which is 2022-11-14 7AM PST (Monday).
  2. Create a weekly recurring transfer on every Tuesday using /transfer/recurring/create with test_clock_id returned from step 1. The recurring schedule starts on 2022-11-15, and ends on 2022-11-30.
  3. Advance the test clock to "2022-11-15T23:59:00-08:00", which is the end of day 2022-11-15 PST (Tuesday).
  4. Since we advanced the test clock to the last minute of Tuesday and the recurring transfer is also scheduled on every Tuesday, we expect to see 1 transfer being created. Inspect the recurring transfer created in step 2 with /transfer/recurring/get. Confirm transfer_ids field now has 1 element, and the status field is "active".
  5. Advance the test clock to "2022-11-29T23:59:00-08:00", which is the end of day 2022-11-29 PST (Tuesday).
  6. Inspect the recurring transfer created in step 2 with /transfer/recurring/get. Confirm transfer_ids field now has 3 elements, and the status field is now "expired".
  7. Advance the test clock to "2022-12-06T23:59:00-08:00", which is the end of day 2022-12-06 PST (Tuesday).
  8. Inspect the recurring transfer created in step 2 with /transfer/recurring/get. Confirm transfer_ids field still has 3 elements, and the status field remains "expired".

errors

Errors

A comprehensive breakdown of all Plaid error codes

Errors overview

Item errors
Occur when an Item may be invalid or not supported on Plaid's platform.
INVALID_MFA OTP Device & Code
INVALID_MFA Questions
INVALID_MFA Selections
NO_AUTH_ACCOUNTS or no-depository-accounts
Institution errors
Occur when there are errors for the requested financial institution.
API errors
Occur during planned maintenance and in response to API errors.
INTERNAL_SERVER_ERROR or plaid-internal-error
Assets errors
Occur for errors related to Asset endpoints.
Payment errors
Occur for errors related to Payment Initiation endpoints.
Virtual Account errors
Occur for errors related to Virtual Account endpoints.
Transactions errors
Occur for errors related to Transactions endpoints.
Transfer errors
Occur for errors related to Transfer endpoints.
Income errors
Occur for errors related to Income endpoints.
Sandbox errors
Occur when invalid parameters are supplied in the Sandbox environment.
Invalid Request errors
Occur when a request is malformed and cannot be processed.
Invalid Input errors
Occur when all fields are provided, but the values provided are incorrect in some way.
Invalid Result errors
Occur when a request is valid, but the output would be unusable for any supported flow.
Rate Limit Exceeded errors
Occur when an excessive number of requests are made in a short period of time.
Link Web errors
Occur when the error is specific to Link on the web platform.
ReCAPTCHA errors
Occur when a ReCAPTCHA challenge has been presented or failed during the link process.
OAuth errors
Occur when there is an error in OAuth authentication.
Micro-deposits errors
Occur when there is an error with micro-deposits.
Partner errors
Occur when there is an error with creating or managing end customers.

Error schema

We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.

error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
Was this helpful?

auth partnerships rize

Add Rize to your app

Use Rize with Plaid Auth to send and receive payments!

Partnership Rize logo

Overview

Plaid and Rize have partnered to help customers seamlessly link verified bank accounts to their Rize-supported products. Rize provides developers access to all of the tools they need to efficiently build, launch, and grow new financial products and services without the need for multiple vendors. Using this integration, bank accounts connected via Plaid can be added to the Rize platform for funding accounts or withdrawing money, without ever sharing sensitive account details.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Rize account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Rize processor_token, which allows you to quickly and securely verify a bank funding source via Rize's API without having to store any sensitive banking information. Utilizing Plaid + Rize enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Rize in order to use the Plaid + Rize integration. You'll also need to enable your Plaid account for the Rize integration.

First, you will need to work with the Rize team to sign up for a Rize account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Rize to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Rize processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Rize, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Rize processor_token. You'll send this token to Rize and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Rize processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'rize',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Rize Production credentials prior to initiating live payment transactions in the Rize API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

balance

Introduction to Balance

Retrieve real-time balance information.

Explore API

Overview

Balance is Plaid's product for receiving real-time Balance information via /accounts/balance/get. This real-time Balance data can be helpful when checking to see if an account has sufficient funds before using it as a funding source for a money transfer. Balance is available for use exclusively in combination with other Plaid products, such as Auth for money movement or account funding use cases, or Transactions for personal financial management use cases.

Balance data

1"balances": {
2  "available": 100,
3  "current": 110,
4  "iso_currency_code": "USD",
5  "limit": null,
6  "unofficial_currency_code": null
7}

Cached and realtime balance

Many Plaid products other than Balance provide balance information as part of the accounts object. However, this data is typically updated about once a day, and cached data is often returned, which is not suitable for situations where you need real-time balance information. For retrieving real-time balance, only /accounts/balance/get should be used. The exception is immediately after an Item has been linked, when the balance information is guaranteed to be recent. Note that because Balance always retrieves fresh data from the institution, latency may be higher when calling /accounts/balance/get than when calling other Plaid endpoints.

If you want to evaluate the risk of an ACH return and need lower latency than /accounts/balance/get, try Signal. Signal uses machine learning instead of real-time balance checks to evaluate the risk of an ACH return, and can return results in approximately one-tenth the time as the Balance endpoint.

Current and available balance

Balance typically returns both current and available balance information. For fraud detection and insufficient funds (NSF) prevention use cases, available balance should be used, as it represents predicted balance net of any pending transactions, while current balance does not take pending transactions into account.

Available balance indicates balance that is available to spend, which is not the same as the overall value of the account. For example, for credit accounts, it indicates the amount that can be spent without hitting the credit limit (net of any pending transactions), while in investment accounts, it indicates the total available cash.

In some cases, a financial institution may not return available balance information. If that happens, you can calculate available balance by starting with the current balance, then using the Transactions product to detect any pending transactions and adjusting the balance accordingly.

Sample app code

For a real-life example of an app that incorporates Balance, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that fetches Balance data to check for sufficient funds before a funds transfer. The Balance code can be found in items.js.

For a tutorial walkthrough of creating a similar app, see Account funding tutorial.

Next steps

To get started building with Balance, see Add Balance to your App.

If you are using Balance as part of an account funding use case, see the Plaid Account Funding Guide for an overview of all required steps.

If you're ready to launch to Production, see the Launch checklist.

errors invalid input

Invalid Input Errors

Guide to troubleshooting invalid input errors

DIRECT_INTEGRATION_NOT_ENABLED

An attempt was made to create an Item without using Link.
Common causes
  • /item/create was called directly, without using Link.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "DIRECT_INTEGRATION_NOT_ENABLED",
5 "error_message": "your client ID is only authorized to use Plaid Link. head to the docs (https://plaid.com/docs) to get started.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INCORRECT_DEPOSIT_VERIFICATION

The user submitted an incorrect Manual Same-Day micro-deposit verification input during Item verification in Link.
Sample user-facing error message
Code is incorrect, 2 attempts remaining: Check the bank statement of your account ending in •••0000 for the $0.01 deposit and try again.
Common causes
  • Your user submitted an incorrect micro-deposit verification input when verifying an account via Manual Same-Day micro-deposits.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INCORRECT_DEPOSIT_VERIFICATION",
5 "error_message": "",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INCORRECT_DEPOSIT_AMOUNTS

This error code has been deprecated. This will only be used for Manual Same-Day micro-deposits customers before January 23, 2023.

The user submitted incorrect Manual Same-Day micro-deposit amounts during Item verification in Link.
Sample user-facing error message
Amounts were incorrect, 2 attempts remaining: Check the account statement of your account ending in 0000 for the two small deposits and try again
Common causes
  • Your user submitted incorrect micro-deposit amounts when verifying an account via Manual Same-Day micro-deposits.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INCORRECT_DEPOSIT_AMOUNTS",
5 "error_message": "",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_ACCESS_TOKEN

Common causes
  • Access tokens are in the format: access-<environment>-<identifier>
  • This error can happen when the access_token you provided is invalid or pertains to a different API environment
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_ACCESS_TOKEN",
5 "error_message": "could not find matching access token",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_ACCOUNT_ID

The supplied account_id is not valid
Common causes

One of the account_id(s) specified in the API call's account_ids object is invalid or does not exist.

  • Your integration is passing a correctly formatted, but invalid account_id for the Item in question.
  • The underlying account may have been closed at the bank, and thus removed from our API.
  • The Item affected is at an institution that uses OAuth-based connections, and the user revoked access to the specific account.
  • The account_id was erroneously removed from our API, either completely or a new account_id was assigned to the same underlying account.
  • You are requesting an account that your user has de-selected in the Account Select v2 update flow.
Troubleshooting steps

Ensure that your integration only uses account_id(s) that belong to the Item in question. Early on in your development it is important to verify that your integration only uses account_id(s), and other Plaid identifiers like item_id, for the Item that they belong to.

Also be sure to preserve the case of any non-numeric characters in Plaid identifiers, as they are case sensitive.

Account churn

If the underlying account has not been closed or changed at the bank and the account_id no longer appears, Plaid may have removed the account entirely or assigned the account a new account_id, a situation known as "account churn".

Some common causes for account churn are:

  • The Item was in an unhealthy state for an extended period of time. If an Item has remained in an error state for over a year, its underlying data may be removed. If the Item is then later refreshed, the Item data will be re-generated, resulting in new account_id data.
  • The bank or user drastically changing the name of the account, e.g. an account named "Savings account" becomes "Jane's vacation fund".
  • The account's mask is changed by the bank, which can occur when banks change their backend systems.

Account churn caused by the latter two reasons is unexpected API behavior. If you experience account churn on an Item that was otherwise healthy, file a Support ticket.

1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_ACCOUNT_ID",
5 "error_message": "failed to find requested account ID for requested item",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_API_KEYS

The client ID and secret included in the request body were invalid. Find your API keys in the Dashboard.
Common causes
  • The API keys are not valid for the environment being used, which can commonly happen when switching between development environments and forgetting to switch API keys
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_API_KEYS",
5 "error_message": "invalid client_id or secret provided",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_AUDIT_COPY_TOKEN

The audit copy token supplied to the server was invalid.
Common causes
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_AUDIT_COPY_TOKEN",
5 "error_message": null,
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_INSTITUTION

The institution_id specified is invalid or does not exist.
Common causes
  • The institution_id specified is invalid or does not exist.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_INSTITUTION",
5 "error_message": "invalid institution_id provided",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_LINK_CUSTOMIZATION

The Link customization is not valid for the request.
Common causes
  • This error can happen when requesting to update account selections with a Link customization that does not enable Account Select v2.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_LINK_CUSTOMIZATION",
5 "error_message": "requested link customization is not set to update account selection",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_LINK_TOKEN

The link_token provided to initialize Link was invalid.
Sample user-facing error message
Username or password incorrect: Check that your credentials are the same that you use for this institution
Common causes
  • The link_token has expired. A link_token lasts at least 30 minutes before expiring.
  • The link_token was already used. A link_token can only be used once, except when working in the Sandbox test environment.
  • The link_token was created in a different environment than the one it was used with. For example, a Sandbox link_token was used in Production.
  • A user entered invalid credentials too many times during the Link flow, invalidating the link_token.
Troubleshooting steps

For more detailed instructions on handling this error, see Handling invalid Link Tokens.

1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_LINK_TOKEN",
5 "error_message": "invalid link_token provided",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_PROCESSOR_TOKEN

The processor_token provided to initialize Link was invalid.
Common causes
  • The processor_token used to initialize Link was invalid.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_PROCESSOR_TOKEN",
5 "error_message": null,
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_PRODUCT

Your client ID does not have access to this product.
Common causes
  • The endpoint you are trying to access must either be manually enabled for your account or requires a different pricing plan.
  • Your integration is using a partner endpoint integration that has not yet been enabled in the Dashboard.
  • Your integration is attempting to call a processor endpoint on an Item that was initialized with products that are not compatible with processor endpoints.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_PRODUCT",
5 "error_message": "products must either be null or a list of strings containing at least one valid product",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_PRODUCTS

The pre-authenticated returning user flow was initiated with a restricted product.
Sample user-facing error message
Something went wrong: There was a problem and we couldn't connect your account. Try entering your username and password again.
Common causes
  • For a returning user, Link was initiated with a product that is restricted from the pre-authenticated returning user flow.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_PRODUCTS",
5 "error_message": "The following products are not allowed for pre-authed items: ['auth'].",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

ADDITIONAL_CONSENT_REQUIRED

The end user has not provided consent to the requested product
Common causes
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "ADDITIONAL_CONSENT_REQUIRED",
5 "error_message": "client does not have user consent to access the PRODUCT_AUTH product",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_PUBLIC_TOKEN

Common causes
  • Public tokens are in the format: public-<environment>-<identifier>
  • This error can happen when the public_token you provided is invalid, pertains to a different API environment, or has expired.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_PUBLIC_TOKEN",
5 "error_message": "could not find matching public token",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_STRIPE_ACCOUNT

The supplied Stripe account is invalid
Common causes

After /processor/stripe/bank_account_token/create was called, Plaid received a response from Stripe indicating that the Stripe account specified in the API call's account_id is invalid.

Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_STRIPE_ACCOUNT",
5 "error_message": "",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_USER_TOKEN

The supplied user token is invalid
Common causes
  • The user token is not associated with the given user ID.
  • The user token is invalid or pertains to a different API environment.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_USER_TOKEN",
5 "error_message": "could not find matching user token",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_WEBHOOK_VERIFICATION_KEY_ID

The key_id provided to the webhook verification endpoint was invalid.
Common causes
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_WEBHOOK_VERIFICATION_KEY_ID",
5 "error_message": "invalid key_id provided. note that key_ids are specific to Plaid environments, and verification requests must be made to the same environment that the webhook was sent from",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

PRODUCT_UNAVAILABLE

Additional products may not be added to Items created in the pre-auth returning user flow.
Common causes
  • A request was made to an Item created via the pre-authenticated returning user flow for a product that the Item was not initialized with during the original Link flow.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "PRODUCT_UNAVAILABLE",
5 "error_message": "Additional products may not be added to this pre-authed item.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

TOO_MANY_VERIFICATION_ATTEMPTS

The user attempted to verify their Manual Same-Day micro-deposit codes more than 3 times and their Item is now permanently locked. The user must retry submitting their account information in Link.
Sample user-facing error message
No attempts remaining: You’ve used up all of your attempts. To continue, connect a different bank
Common causes
  • Your user repeatedly submitted incorrect micro-deposit codes when verifying an account via Manual Same-Day micro-deposits.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "TOO_MANY_VERIFICATION_ATTEMPTS",
5 "error_message": "",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

UNAUTHORIZED_ENVIRONMENT

Your client ID does not have access to this API environment. See which environments you are enabled for from the Dashboard.
Sample user-facing error message
Unauthorized environment: Your Client ID is not authorized to access this API environment. Contact Support to gain access
Common causes
  • You may not be enabled for the environment you are using.
  • Your code may be calling a deprecated endpoint.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "UNAUTHORIZED_ENVIRONMENT",
5 "error_message": "you are not authorized to create items in this api environment. Go to the Dashboard (https://dashboard.plaid.com) to see which environments you are authorized for.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

UNAUTHORIZED_ROUTE_ACCESS

Your client ID does not have access to this route.
Common causes
  • The endpoint you are trying to access must be manually enabled for your account.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "UNAUTHORIZED_ROUTE_ACCESS",
5 "error_message": "you are not authorized to access this route in this api environment.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

USER_PERMISSION_REVOKED

The end user has revoked access to their data.
Common causes
  • The end user revoked access to their data via the Plaid consumer portal at my.plaid.com.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "USER_PERMISSION_REVOKED",
5 "error_message": "the holder of this account has revoked their permission for your application to access it",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

link react native ios setup

iOS Setup

Reference for setting up iOS for use with the Link React Native SDK

iOS Setup

Add Plaid to your project’s Podfile as follows (likely located at ios/Podfile). The latest version is version.

iOS SDK versions prior to 4.1.0 (released January 2023) will no longer support Chase OAuth flows as of September 30, 2023. If you are using an older version of the iOS SDK, make sure to upgrade before that date. For more details, see the in-process webview deprecation notice.

1pod 'Plaid', '~> <insert latest version>'

Then install your CocoaPods dependencies:

1(cd ios && pod install)

That's all you need to do if using a recent react-native version with autolinking support. To begin coding your integration, see Opening Link.

Manual Integration

If using a version of react-native without autolinking support, then you will need to:

1react-native link react-native-plaid-link-sdk

followed by:

  1. In Xcode, in the Project Navigator, right click Libraries ▶ Add Files to [your project's name]
  2. Go to node_modules ▶ react-native-plaid-link-sdk ▶ ios and add RNLinksdk.xcodeproj
  3. In Xcode, in the project navigator, select your project. Add libRNLinksdk.a to your project's Build Phases ▶ Link Binary With Libraries
  4. Run your project (Cmd+R).

Now your React Native application is linked to the Plaid React Native SDK for iOS development. To begin coding your integration, see Opening Link.

OAuth Setup

All Plaid integrations are required to support OAuth; for full details on OAuth support, see the OAuth guide. OAuth support on iOS requires the following client-side configuration:

virtual accounts

Introduction to Virtual Accounts

Manage the entire lifecycle of a payment

Explore API

Virtual account functionality is currently supported only in Sandbox and Production.

Overview

Plaid's virtual account API allows you to collect domestic payments, initiate payouts and refunds, and streamline reconciliation processes. Virtual accounts provide granular control and visibility throughout the entire lifecycle of a payment. While Plaid’s Payment Initiation API handles account funding use cases, virtual accounts can be layered on top of Payment Initiation functionality to provide insight into the settlement status of all transactions, pay out to your merchants, allow end users to withdraw their funds, and issue refunds.

For example, if you have a brokerage app, you can use Payment Initiation for end users to fund their accounts. Payment Confirmation will inform you when your end users' payments have settled so you can release these funds for your end users to purchase equities. When your end users sell their equity purchases, you can use Payouts to let them cash out their earnings.

See the Add Virtual Accounts to your App guide to learn more about how to implement virtual accounts.

Testing Virtual Accounts

You can immediately start using virtual accounts in Sandbox. For Production access you will need to first request access by submitting a product access request Support ticket explaining your use case.

Next steps

To get started building with Virtual Accounts, see Add Virtual Accounts to your App.

api products signal

Signal endpoints

API Reference guide for the Signal product

Endpoints
/signal/evaluateRetrieve Signal scores
/signal/decision/reportReport whether you initiated an ACH transaction
/signal/return/reportReport a return for an ACH transaction
/signal/prepareAdd Signal to a newly linked item
See also
/processor/token/createCreate a token for using Signal with a processing partner
/processor/signal/evaluateRetrieve Signal scores as a processor partner
/processor/signal/decision/reportReport whether you initiated an ACH transaction as a processor partner
/processor/signal/return/reportReport a return for an ACH transaction as a processor partner

/signal/evaluate

Evaluate a planned ACH transaction

Use /signal/evaluate to evaluate a planned ACH transaction to get a return risk assessment (such as a risk score and risk tier) and additional risk signals.
In order to obtain a valid score for an ACH transaction, Plaid must have an access token for the account, and the Item must be healthy (receiving product updates) or have recently been in a healthy state. If the transaction does not meet eligibility requirements, an error will be returned corresponding to the underlying cause. If /signal/evaluate is called on the same transaction multiple times within a 24-hour period, cached results may be returned. For more information please refer to the error documentation on Item errors and Link in Update Mode.
Note: This request may take some time to complete if Signal is being added to an existing Item. This is because Plaid must communicate directly with the institution when retrieving the data for the first time.

signal/evaluate

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
account_id
requiredstring
The Plaid account_id of the account that is the funding source for the proposed transaction. The account_id is returned in the /accounts/get endpoint as well as the onSuccess callback metadata.
This will return an INVALID_ACCOUNT_ID error if the account has been removed at the bank or if the account_id is no longer valid.
client_transaction_id
requiredstring
The unique ID that you would like to use to refer to this transaction. For your convenience mapping your internal data, you could use your internal ID/identifier for this transaction. The max length for this field is 36 characters.

Min length: 1
Max length: 36
amount
requirednumber
The transaction amount, in USD (e.g. 102.05)

Format: double
user_present
boolean
true if the end user is present while initiating the ACH transfer and the endpoint is being called; false otherwise (for example, when the ACH transfer is scheduled and the end user is not present, or you call this endpoint after the ACH transfer but before submitting the Nacha file for ACH processing).
client_user_id
string
A unique ID that identifies the end user in your system. This ID is used to correlate requests by a user with multiple Items. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.
is_recurring
boolean
true if the ACH transaction is a recurring transaction; false otherwise
default_payment_method
string
The default ACH or non-ACH payment method to complete the transaction. SAME_DAY_ACH: Same Day ACH by NACHA. The debit transaction is processed and settled on the same day NEXT_DAY_ACH: Next Day ACH settlement for debit transactions, offered by some payment processors STANDARD_ACH: standard ACH by NACHA REAL_TIME_PAYMENTS: real-time payments such as RTP and FedNow DEBIT_CARD: if the default payment is over debit card networks MULTIPLE_PAYMENT_METHODS: if there is no default debit rail or there are multiple payment methods Possible values: SAME_DAY_ACH, NEXT_DAY_ACH, STANDARD_ACH, REAL_TIME_PAYMENTS, DEBIT_CARD, MULTIPLE_PAYMENT_METHODS
user
object
Details about the end user initiating the transaction (i.e., the account holder).
name
object
The user's legal name
prefix
string
The user's name prefix (e.g. "Mr.")
given_name
string
The user's given name. If the user has a one-word name, it should be provided in this field.
middle_name
string
The user's middle name
family_name
string
The user's family name / surname
suffix
string
The user's name suffix (e.g. "II")
phone_number
string
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567"
email_address
string
The user's email address.
address
object
Data about the components comprising an address.
city
string
The full city name
region
string
The region or state Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
string
The postal code
country
string
The ISO 3166-1 alpha-2 country code
device
object
Details about the end user's device
ip_address
string
The IP address of the device that initiated the transaction
user_agent
string
The user agent of the device that initiated the transaction (e.g. "Mozilla/5.0")
Select Language
1const eval_request = {
2  access_token: "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175",
3  account_id: "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
4  client_transaction_id: "txn12345",
5  amount: 123.45,
6  client_user_id: "user1234",
7  user: {
8    name: {
9      prefix: "Ms.",
10      given_name: "Jane",
11      middle_name: "Leah",
12      family_name: "Doe",
13      suffix: "Jr.",
14    },
15    phone_number: "+14152223333",
16    email_address: "jane.doe@example.com",
17    address: {
18      street: "2493 Leisure Lane",
19      city: "San Matias",
20      region: "CA",
21      postal_code: "93405-2255",
22      country: "US",
23    },
24  },
25  device: {
26    ip_address: "198.30.2.2",
27    user_agent:"Mozilla/5.0 (iPhone; CPU iPhone OS 13_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Mobile/15E148 Safari/604.1",
28  },
29  user_present: true,
30};
31
32try {
33  const eval_response = await plaidClient.signalEvaluate(eval_request);
34  const core_attributes = eval_response.data.core_attributes;
35  const scores = eval_response.data.scores;
36} catch (error) {
37  // handle error
38}
signal/evaluate

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
scores
object
Risk scoring details broken down by risk category.
customer_initiated_return_risk
object
The object contains a risk score and a risk tier that evaluate the transaction return risk of an unauthorized debit. Common return codes in this category include: "R05", "R07", "R10", "R11", "R29". These returns typically have a return time frame of up to 60 calendar days. During this period, the customer of financial institutions can dispute a transaction as unauthorized.
score
integer
A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood.

Minimum: 1
Maximum: 99
risk_tier
integer
A tier corresponding to the projected likelihood that the transaction, if initiated, will be subject to a return.
In the customer_initiated_return_risk object, there are five risk tiers corresponding to the scores: 1: Predicted customer-initiated return incidence rate between 0.00% - 0.02% 2: Predicted customer-initiated return incidence rate between 0.02% - 0.05% 3: Predicted customer-initiated return incidence rate between 0.05% - 0.1% 4: Predicted customer-initiated return incidence rate between 0.1% - 0.5% 5: Predicted customer-initiated return incidence rate greater than 0.5%

Minimum: 1
Maximum: 5
bank_initiated_return_risk
object
The object contains a risk score and a risk tier that evaluate the transaction return risk because an account is overdrawn or because an ineligible account is used. Common return codes in this category include: "R01", "R02", "R03", "R04", "R06", "R08", "R09", "R13", "R16", "R17", "R20", "R23". These returns have a turnaround time of 2 banking days.
score
integer
A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood.

Minimum: 1
Maximum: 99
risk_tier
integer
In the bank_initiated_return_risk object, there are eight risk tiers corresponding to the scores: 1: Predicted bank-initiated return incidence rate between 0.0% - 0.5% 2: Predicted bank-initiated return incidence rate between 0.5% - 1.5% 3: Predicted bank-initiated return incidence rate between 1.5% - 3% 4: Predicted bank-initiated return incidence rate between 3% - 5% 5: Predicted bank-initiated return incidence rate between 5% - 10% 6: Predicted bank-initiated return incidence rate between 10% - 15% 7: Predicted bank-initiated return incidence rate between 15% and 50% 8: Predicted bank-initiated return incidence rate greater than 50%

Minimum: 1
Maximum: 8
core_attributes
object
The core attributes object contains additional data that can be used to assess the ACH return risk. Examples of data include:
days_since_first_plaid_connection: The number of days since the first time the Item was connected to an application via Plaid plaid_connections_count_7d: The number of times the Item has been connected to applications via Plaid over the past 7 days plaid_connections_count_30d: The number of times the Item has been connected to applications via Plaid over the past 30 days total_plaid_connections_count: The number of times the Item has been connected to applications via Plaid is_savings_or_money_market_account: Indicates whether the ACH transaction funding account is a savings/money market account
For the full list and detailed documentation of core attributes available, or to request that core attributes not be returned, contact Sales or your Plaid account manager
warnings
[object]
If bank information was not available to be used in the Signal model, this array contains warnings describing why bank data is missing. If you want to receive an API error instead of Signal scores in the case of missing bank data, file a support ticket or contact your Plaid account manager.
warning_type
string
A broad categorization of the warning. Safe for programmatic use.
warning_code
string
The warning code identifies a specific kind of warning that pertains to the error causing bank data to be missing. Safe for programmatic use. For more details on warning codes, please refer to Plaid standard error codes documentation. In case you receive the ITEM_LOGIN_REQUIRED warning, we recommend re-authenticating your user by implementing Link's update mode. This will guide your user to fix their credentials, allowing Plaid to start fetching data again for future Signal requests.
warning_message
string
A developer-friendly representation of the warning type. This may change over time and is not safe for programmatic use.
1{
2  "scores": {
3    "customer_initiated_return_risk": {
4      "score": 9,
5      "risk_tier": 1
6    },
7    "bank_initiated_return_risk": {
8      "score": 72,
9      "risk_tier": 7
10    }
11  },
12  "core_attributes": {
13    "days_since_first_plaid_connection": 510,
14    "plaid_connections_count_7d": 6,
15    "plaid_connections_count_30d": 7,
16    "total_plaid_connections_count": 15,
17    "is_savings_or_money_market_account": false
18  },
19  "warnings": [],
20  "request_id": "mdqfuVxeoza6mhu"
21}
Was this helpful?

/signal/decision/report

Report whether you initiated an ACH transaction

After calling /signal/evaluate, call /signal/decision/report to report whether the transaction was initiated. This endpoint will return an INVALID_FIELD error if called a second time with a different value for initiated.

signal/decision/report

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_transaction_id
requiredstring
Must be the same as the client_transaction_id supplied when calling /signal/evaluate

Min length: 1
Max length: 36
initiated
requiredboolean
true if the ACH transaction was initiated, false otherwise.
This field must be returned as a boolean. If formatted incorrectly, this will result in an INVALID_FIELD error.
days_funds_on_hold
integer
The actual number of days (hold time) since the ACH debit transaction that you wait before making funds available to your customers. The holding time could affect the ACH return rate.
For example, use 0 if you make funds available to your customers instantly or the same day following the debit transaction, or 1 if you make funds available the next day following the debit initialization.

Minimum: 0
decision_outcome
string
The payment decision from the risk assessment.
APPROVE: approve the transaction without requiring further actions from your customers. For example, use this field if you are placing a standard hold for all the approved transactions before making funds available to your customers. You should also use this field if you decide to accelerate the fund availability for your customers.
REVIEW: the transaction requires manual review
REJECT: reject the transaction
TAKE_OTHER_RISK_MEASURES: for example, placing a longer hold on funds than those approved transactions or introducing customer frictions such as step-up verification/authentication
NOT_EVALUATED: if only logging the Signal results without using them
Possible values: APPROVE, REVIEW, REJECT, TAKE_OTHER_RISK_MEASURES, NOT_EVALUATED

Possible values: APPROVE, REVIEW, REJECT, TAKE_OTHER_RISK_MEASURES, NOT_EVALUATED
payment_method
string
The payment method to complete the transaction after the risk assessment. It may be different from the default payment method.
SAME_DAY_ACH: Same Day ACH by NACHA. The debit transaction is processed and settled on the same day
NEXT_DAY_ACH: Next Day ACH settlement for debit transactions, offered by some payment processors
STANDARD_ACH: standard ACH by NACHA
REAL_TIME_PAYMENTS: real-time payments such as RTP and FedNow
DEBIT_CARD: if the default payment is over debit card networks
MULTIPLE_PAYMENT_METHODS: if there is no default debit rail or there are multiple payment methods
Possible values: SAME_DAY_ACH, NEXT_DAY_ACH, STANDARD_ACH, REAL_TIME_PAYMENTS, DEBIT_CARD, MULTIPLE_PAYMENT_METHODS

Possible values: SAME_DAY_ACH, NEXT_DAY_ACH, STANDARD_ACH, REAL_TIME_PAYMENTS, DEBIT_CARD, MULTIPLE_PAYMENT_METHODS
amount_instantly_available
number
The amount (in USD) made available to your customers instantly following the debit transaction. It could be a partial amount of the requested transaction (example: 102.05).

Format: double
Select Language
1const decision_report_request = {
2  client_transaction_id: "txn12345",
3  initiated: true,
4  days_funds_on_hold: 3,
5};
6
7try {
8  const decision_report_response = await plaidClient.signalDecisionReport(decision_report_request);
9  const decision_request_id = decision_report_response.data.request_id;
10} catch (error) {
11  // handle error
12}
signal/decision/report

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "mdqfuVxeoza6mhu"
3}
Was this helpful?

/signal/return/report

Report a return for an ACH transaction

Call the /signal/return/report endpoint to report a returned transaction that was previously sent to the /signal/evaluate endpoint. Your feedback will be used by the model to incorporate the latest risk trend in your portfolio.

signal/return/report

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_transaction_id
requiredstring
Must be the same as the client_transaction_id supplied when calling /signal/evaluate

Min length: 1
Max length: 36
return_code
requiredstring
Must be a valid ACH return code (e.g. "R01")
If formatted incorrectly, this will result in an INVALID_FIELD error.
returned_at
string
Date and time when you receive the returns from your payment processors, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ).

Format: date-time
Select Language
1const return_report_request = {
2  client_transaction_id: "txn12345",
3  return_code: "R01",
4};
5
6try {
7  const return_report_response = await plaidClient.signalReturnReport(return_report_request);
8  const request_id = return_report_response.data.request_id;
9  console.log(request_id)
10} catch (error) {
11  // handle error
12}
signal/return/report

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "mdqfuVxeoza6mhu"
3}
Was this helpful?

/signal/prepare

Opt-in an Item to Signal

When Link is not initialized with Signal, call /signal/prepare to opt-in that Item to the Signal data collection process, developing a Signal score.
If you are using other Plaid products after Link, e.g. Identity or Assets, call /signal/prepare after those product calls are complete.
Example flow: Link is initialized with Auth, call /auth/get for the account and routing number, call /identity/get to retrieve bank ownership details, then call /signal/prepare to begin Signal data collection. Later, once you have obtained details about the proposed transaction from the user, call /signal/evaluate for a Signal score. For more information please see Recommendations for initializing Link with specific product combinations.

signal/prepare

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
Select Language
1const prepare_request = {
2  client_id: "7f57eb3d2a9j6480121fx361",
3  secret: "79g03eoofwl8240v776r2h667442119",
4  access_token: "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175",
5};
6
7try {
8  const prepare_response = await plaidClient.signalPrepare(prepare_request);
9  const request_id = prepare_response.data.request_id;
10  console.log(request_id)
11} catch (error) {
12  // handle error
13}
signal/prepare

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "mdqfuVxeoza6mhu"
3}
Was this helpful?

account billing

Plaid billing

Learn about pricing, what is considered a billable event, and how to monitor your bill

Pricing plans

Plaid offers three types of pricing plans:

  • Pay as you go – has no minimum spend or commitment.
  • Growth – minimum spend of $100/month, 3 month commitment. Lower per-use costs than pay as you go plans.
  • Custom (aka Scale) – minimum spend (typically $500/month) and annual commitment but lower per-use costs than pay as you go or growth plans. Minimums can apply across the entire Plaid account or by product.

For customers based in Europe, only Custom plans are offered. In addition, Payment Initiation, Signal, and Transfer are currently offered only via Custom plans.

Pricing information

To view the exact pricing you may be eligible for, apply for Production access. Pricing information for pay-as-you-go and growth plans will be displayed on the last page before you submit your access request. For exact pricing details for scale plans, select the scale pricing option on the last page, and Sales will get in touch to inform you what volume discounts you may be eligible for. Or, you can contact Sales via the contact form.

Pricing models

Plaid has multiple different pricing models, depending on the product. These models only apply to Production traffic; usage of Sandbox and Development environments is always free.

Note that the details outlined below are general information and guidance about typical pricing structures and policies for new customers. Your specific pricing and billing structure is governed by your agreement with Plaid. If you have questions about your bill, contact Support.

Endpoints that are not associated with any particular product are generally available to Plaid customers free of charge. Examples of these free-to-use endpoints include Institutions endpoints, Item endpoints, /accounts/get (not to be confused with /accounts/balance/get, which is associated with the Balance product), and token management endpoints.

One-time fee

You will incur charges for one-time fee products whenever an Item is initialized with that product. This occurs when an Item has been successfully created by Link and this product was included in Link's product array. An Item is considered successfully created if an access_token was generated. If the Item was not initialized with the product at the time of creation, it can also be initialized later by calling a product endpoint belonging to that product on the Item.

For Document Income and Payroll Income, charges will be incurred when data is available to be accessed. This will typically be indicated by the INCOME_VERIFICATION webhook firing with the status of VERIFICATION_STATUS_PROCESSING_COMPLETE.

When using Transfer, each Item initialized with Transfer will incur the one-time Auth fee, and no additional fee will be incurred for using Auth endpoints with that Item.

For one-time fee products, it does not matter how many API calls are made for the Item; the cost is the same regardless of whether the product's endpoints are called many times or zero times.

Products that use one-time fee pricing are: Auth, Identity, and Income.

Subscription fee

The subscription fee model is similar to the one-time fee model, except that the Item will incur a monthly subscription fee as long as it exists, even if API calls cannot be successfully made for the Item. Removing the Item will end the subscription. Once an Item has been initialized with a subscription fee product, it is not possible to end the subscription without removing the Item via /item/remove. Plaid's subscription cycle is based on calendar months in the UTC time zone; each month begins a new cycle. Fees for Items created or removed in the middle of the month are not pro-rated.

Products that use subscription fee pricing are: Transactions (except for the /transactions/refresh endpoint), Liabilities, and Investments.

Per-request flat fee

For per-request flat fee products, a flat fee is charged for each successful API call to that product endpoint.

Products and endpoints that use per-request flat fee pricing are: Balance (/accounts/balance/get), /transactions/refresh, /asset_report/audit_copy/create, /asset_report/pdf/get, and Signal (/signal/evaluate).

Per-request flexible fee

For per-request flexible fee products, a fee is charged for each successful API call to that product endpoint. The fee will vary depending on the amount of information requested in the API request.

Products that use per-request flexible fee pricing are: Assets (pricing depends on number of days of transaction history requested and quantity of Items in the Asset Report) and Enrich (pricing depends on quantity of transactions sent for enrichment).

Per-payment fee

For per-payment fee products, a fee is charged for each payment initiated with the product. A payment is considered initiated if the end user reached the end of the payment flow and received a confirmation success screen. Standing orders (recurring payments) are considered a single payment but are billed on a separate pricing schedule from one-time payments. Fees will vary depending on the network used to transfer the payment.

The per-payment fee is charged even if the payment is later reversed or clawed back. In such cases, a reversed payment fee may be charged as well.

When using Transfer, each Item initialized with Transfer will also be initialized with Auth and will incur a one-time Auth fee in addition to the per-payment Transfer fee.

Products that use per-payment fee pricing are: Payment Initiation (UK and Europe), Transfer, and Transfer UI.

Monitor fee model

Monitor uses a model with two fees:

  • A base fee, which is incurred the first time a new user is scanned
  • A rescanning fee, which is incurred based on the number of users rescanned each month

The rescanning fee is calculated based on the number of users on a rescanning program in a given month and works similarly to the subscription fee model. Plaid's subscription cycle is based on calendar months in the UTC time zone; each month begins a new cycle. Fees for users added to or removed from a rescanning program in the middle of the month are not pro-rated.

To avoid being rebilled for a user you no longer need recurring scans for (e.g., a user who has closed their account with you), create a program specifically for former users, make sure rescans are disabled, and move the user into that program when they are offboarded from your system.

Identity Verification fee model

For Identity Verification, a fee is charged based on the end user performing certain activities during the Link flow. The following events are billed:

  • Base check (the first verification check run, typically when the end user enters their phone number to begin SMS verification. If this is skipped, the base check fee will be incurred later on. For example, if the SMS check is skipped in favor of the document check, the document check will incur both the base check fee and the document check fee.)
  • Lightning verification (cost varies based on the end user's country, see your pricing contract for details)
  • Document check
  • Selfie check

If a retry is issued for a session, the retry will be billed like a new session, including the base check and any other verification checks included in the retried session.

Partnerships pricing

If you are using a Plaid partner, you will be charged for Plaid API usage performed by the partner using your processor token in the same way as if the calls had been made by you. If you have questions about the partner's API activity, contact the Plaid partner.

Viewing billable activity and invoices

To view billable activity for your account, see the Usage page on the developer dashboard.

Invoices will be sent each month to the billing contact configured for the team.

Updating payment information

Pay as you go customers can update payment method and billing contact information on the developer dashboard. Custom plan customers should contact their account manager to update this information.

Updating products or pricing

To view your currently enabled products, see the Products page on the Dashboard under the Team Settings section. To add additional products to your Plaid account you can submit the product request form located on the Dashboard. This form is also accessible via the Products page. To remove products or to switch between Custom, Growth, or Pay-as-you-go pricing plans, contact Support or your Plaid Account Manager.

assets partnerships ocrolus

Add Ocrolus to your app

Use Ocrolus with Plaid Assets to digitize data collection

Ocrolus partnership

Plaid and Ocrolus have partnered to offer lenders an easier way to access bank data to make informed loan decisions. Plaid enables businesses to instantly connect a customer's bank account, giving them the ability to authenticate and retrieve account details directly from the financial institution. Ocrolus digitizes bank and credit card statements from all US financial institutions to help lenders digitize their data collection for cash-flow analysis.

With the Plaid + Ocrolus integration, your users can verify their accounts in seconds by inputting their banking credentials in Plaid’s front-end module. Plaid will retrieve the relevant bank information and pass it to Ocrolus for further digestion and reporting in a seamless, secure fashion. Plaid’s mobile-friendly module handles input validation, error handling, and multi-factor authentication, providing a seamless onboarding experience to convert more users for your business.

Getting started

You'll first want to familiarize yourself with Plaid Link, a drop-in integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to create or be an existing Ocrolus customer in order to add a bank account.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment and verification of assets. From there, you'll receive a Plaid access_token, which you can use generate an Ocrolus processor_token and/or audit_copy_token, depending on your use case, which allow you to quickly and securely verify banking information via the Ocrolus API without having to store that sensitive information yourself.

Instructions

Set up your Plaid and Ocrolus accounts

You'll need accounts at both Plaid and Ocrolus in order to use the Plaid + Ocrolus integration. You'll also need to enable your Plaid account for the Ocrolus integration.

First, you will need to work with the Ocrolus team to sign up for an Ocrolus account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one. Your account will be automatically enabled for integration access.

To verify that your Plaid account is enabled for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Ocrolus to enable the integration.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. View the documentation for a full list of link_token configurations.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Ocrolus processor_token.

Select Language
1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onLoad: function() {
9          // The Link module finished loading.
10      },
11      onSuccess: function(public_token, metadata) {
12        // The onSuccess function is called when the user has
13        // successfully authenticated and selected an account to
14        // use.
15        //
16        // When called, you will send the public_token
17        // and the selected account ID, metadata.account_id,
18        // to your backend app server.
19        //
20        // sendDataToBackendServer({
21        //   public_token: public_token,
22        //   account_id: metadata.account_id
23        // });
24        console.log('Public Token: ' + public_token);
25        console.log('Customer-selected account ID: ' + metadata.account_id);
26      },
27      onExit: function(err, metadata) {
28        // The user exited the Link flow.
29        if (err != null) {
30            // The user encountered a Plaid API error
31            // prior to exiting.
32        }
33        // metadata contains information about the institution
34        // that the user selected and the most recent
35        // API request IDs.
36        // Storing this information can be helpful for support.
37      },
38    });
39  })();
40
41  // Trigger the authentication view
42  document.getElementById('linkButton').onclick = function() {
43    linkHandler.open();
44  };
45</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

Once you have the access_token for the Item, you can create an Ocrolus processor_token and/or audit_copy_token. You'll send these tokens to Ocrolus and they will use them to securely retrieve banking information from Plaid.

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest, AssetReportAuditCopyCreateRequest } = require('plaid');
2// Change sandbox to development to test with live users;
3// Change to production when you're ready to go live!
4const configuration = new Configuration({
5  basePath: PlaidEnvironments[process.env.PLAID_ENV],
6  baseOptions: {
7    headers: {
8      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
9      'PLAID-SECRET': process.env.PLAID_SECRET,
10      'Plaid-Version': '2020-09-14',
11    },
12  },
13});
14
15const plaidClient = new PlaidApi(configuration);
16
17try {
18  // Exchange the public_token from Plaid Link for an access token.
19  const tokenResponse = await plaidClient.itemPublicTokenExchange({
20    public_token: PUBLIC_TOKEN,
21  });
22  const accessToken = tokenResponse.access_token;
23
24  // Create a processor token for a specific account id.
25  const request: ProcessorTokenCreateRequest = {
26    access_token: accessToken,
27    account_id: accountID,
28    processor: 'ocrolus',
29  };
30  const processorTokenResponse = await plaidClient.processorTokenCreate(
31    request,
32  );
33  const processorToken = processorTokenResponse.processor_token;
34
35  // Create an Asset Report for the specific access token.
36  const request: AssetReportCreateRequest = {
37    access_tokens: [accessToken],
38    days_requested: 60,
39    options: {},
40  };
41  const response = await plaidClient.assetReportCreate(request);
42  const assetReportId = response.data.asset_report_id;
43  const assetReportToken = response.data.asset_report_token;
44
45  // Create an audit copy token for the Asset Report.
46  const request: AssetReportAuditCopyCreateRequest = {
47    asset_report_token: createResponse.data.asset_report_token,
48    auditor_id: 'ocrolus',
49  };
50  const response = await plaidClient.assetReportAuditCopyCreate(request);
51  const auditCopyToken = response.data.audit_copy_token;
52} catch (error) {
53  // handle error
54}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "UNIQUE_REQUEST_ID"
4}

For a valid audit_copy_token request, the API will return a JSON response similar to:

1{
2  "audit_copy_token": "a-sandbox-3TAU2CWVYBDVRHUCAAAI27ULU4",
3  "request_id": "UNIQUE_REQUEST_ID"
4}

For more information on creating Asset Report audit_copy_tokens, see the documentation for the Assets product.

Testing your Ocrolus integration

You can create Ocrolus processor_tokens in Sandbox (sandbox.plaid.com, allows testing with simulated users). To test the integration in Sandbox mode, use the Plaid Sandbox credentials when launching Link with a link_token created in the Sandbox environment.

To move to Development (a free environment that allows limited access with real users) or Production, request access from the Dashboard. You will want to ensure that you have valid Ocrolus Production credentials prior to connecting bank accounts in the Ocrolus API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

api products auth

Auth

API reference for Auth endpoints and webhooks

Retrieve bank account information to set up electronic funds transfers, such as ACH payments in the US, EFT payments in Canada, BACS payments in the UK, and IBAN / SIC payments in the EU.

Endpoints
/auth/getFetch account information
/bank_transfer/event/listSearch for updates on micro-deposit verification statuses based on filter criteria
/bank_transfer/event/syncGet updates on micro-deposit verification statuses using a cursor
See also
/processor/token/createCreate a token for using Auth with a processing partner
/sandbox/processor_token/createCreate a token for testing Auth with a processing partner
/processor/stripe/bank_account_token/createCreate a token for using Auth with Stripe as a processing partner
/sandbox/item/set_verification_statusChange a Sandbox Item's micro-deposit verification status
Webhooks
AUTOMATICALLY_VERIFIEDItem has been verified
VERIFICATION_EXPIREDItem verification has failed
BANK_TRANSFERS_EVENTS_UPDATENew micro-deposit verification events available

Endpoints

/auth/get

Retrieve auth data

The /auth/get endpoint returns the bank account and bank identification numbers (such as routing numbers, for US accounts) associated with an Item's checking and savings accounts, along with high-level account data and balances when available.
Note: This request may take some time to complete if auth was not specified as an initial product when creating the Item. This is because Plaid must communicate directly with the institution to retrieve the data.
Versioning note: In API version 2017-03-08, the schema of the numbers object returned by this endpoint is substantially different. For details, see Plaid API versioning.

auth/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
options
object
An optional object to filter /auth/get results.
account_ids
[string]
A list of account_ids to retrieve for the Item. Note: An error will be returned if a provided account_id is not associated with the Item.
Select group for content switcher
Select Language
1const request: AuthGetRequest = {
2  access_token: accessToken,
3};
4try {
5  const response = await plaidClient.authGet(request);
6  const accountData = response.data.accounts;
7  const numbers = response.data.numbers;
8} catch (error) {
9  // handle error
10}
auth/get

Response fields and example

accounts
[object]
The accounts for which numbers are being retrieved.
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullablenumber
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullablenumber
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullablenumber
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullablestring
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
numbers
object
An object containing identifying numbers used for making electronic transfers to and from the accounts. The identifying number type (ACH, EFT, IBAN, or BACS) used will depend on the country of the account. An account may have more than one number type. If a particular identifying number type is not used by any accounts for which data has been requested, the array for that type will be empty.
ach
[object]
An array of ACH numbers identifying accounts.
account_id
string
The Plaid account ID associated with the account numbers
account
string
The ACH account number for the account.
Note that when using OAuth with Chase Bank (ins_56), Chase will issue "tokenized" routing and account numbers, which are not the user's actual account and routing numbers. These tokenized account numbers (also known as TANs) should work identically to normal account and routing numbers. The digits returned in the mask field will continue to reflect the actual account number, rather than the tokenized account number; for this reason, when displaying account numbers to the user to help them identify their account in your UI, always use the mask rather than truncating the account number. If a user revokes their permissions to your app, the tokenized numbers will continue to work for ACH deposits, but not withdrawals.
routing
string
The ACH routing number for the account. If the institution is ins_56, this may be a tokenized routing number. For more information, see the description of the account field.
wire_routing
nullablestring
The wire transfer routing number for the account, if available
eft
[object]
An array of EFT numbers identifying accounts.
account_id
string
The Plaid account ID associated with the account numbers
account
string
The EFT account number for the account
institution
string
The EFT institution number for the account
branch
string
The EFT branch number for the account
international
[object]
An array of IBAN numbers identifying accounts.
account_id
string
The Plaid account ID associated with the account numbers
iban
string
The International Bank Account Number (IBAN) for the account
bic
string
The Bank Identifier Code (BIC) for the account
bacs
[object]
An array of BACS numbers identifying accounts.
account_id
string
The Plaid account ID associated with the account numbers
account
string
The BACS account number for the account
sort_code
string
The BACS sort code for the account
item
object
Metadata about the Item.
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
nullablestring
The Plaid Institution ID associated with the Item. Field is null for Items created via Same Day Micro-deposits.
webhook
nullablestring
The URL registered to receive webhooks for the Item.
error
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
available_products
[string]
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
billed_products
[string]
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available_products. Note - billed_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
products
[string]
A list of initialized products for the Item. In almost all cases, this will be the same as the billed_products field. For some products, it is possible for the product to be initialized on an Item but not yet billed (e.g. Assets, before /asset_report/create has been called), in which case the product may appear in products but not in billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consented_products
[string]
A list of products that have gone through consent collection for the Item. Only present for those enabled in the Data Transparency beta. If you are not enrolled in Data Transparency, this field is not used.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consent_expiration_time
nullablestring
The RFC 3339 timestamp after which the consent provided by the end user will expire. Upon consent expiration, the item will enter the ITEM_LOGIN_REQUIRED error state. To circumvent the ITEM_LOGIN_REQUIRED error and maintain continuous consent, the end user can reauthenticate via Link’s update mode in advance of the consent expiration time.
Note - This is only relevant for certain OAuth-based institutions. For all other institutions, this field will be null.

Format: date-time
update_type
string
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication.
background - Item can be updated in the background
user_present_required - Item requires user interaction to be updated

Possible values: background, user_present_required
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "accounts": [
3    {
4      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
5      "balances": {
6        "available": 100,
7        "current": 110,
8        "limit": null,
9        "iso_currency_code": "USD",
10        "unofficial_currency_code": null
11      },
12      "mask": "9606",
13      "name": "Plaid Checking",
14      "official_name": "Plaid Gold Checking",
15      "subtype": "checking",
16      "type": "depository"
17    }
18  ],
19  "numbers": {
20    "ach": [
21      {
22        "account": "9900009606",
23        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
24        "routing": "011401533",
25        "wire_routing": "021000021"
26      }
27    ],
28    "eft": [
29      {
30        "account": "111122223333",
31        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
32        "institution": "021",
33        "branch": "01140"
34      }
35    ],
36    "international": [
37      {
38        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
39        "bic": "NWBKGB21",
40        "iban": "GB29NWBK60161331926819"
41      }
42    ],
43    "bacs": [
44      {
45        "account": "31926819",
46        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
47        "sort_code": "601613"
48      }
49    ]
50  },
51  "item": {
52    "available_products": [
53      "balance",
54      "identity",
55      "payment_initiation",
56      "transactions"
57    ],
58    "billed_products": [
59      "assets",
60      "auth"
61    ],
62    "consent_expiration_time": null,
63    "error": null,
64    "institution_id": "ins_117650",
65    "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
66    "update_type": "background",
67    "webhook": "https://www.genericwebhookurl.com/webhook"
68  },
69  "request_id": "m8MDnv9okwxFNBV"
70}
Was this helpful?

/bank_transfer/event/list

List bank transfer events

Use the /bank_transfer/event/list endpoint to get a list of Plaid-initiated ACH or bank transfer events based on specified filter criteria. When using Auth with micro-deposit verification enabled, this endpoint can be used to fetch status updates on ACH micro-deposits. For more details, see micro-deposit events.

bank_transfer/event/list

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
start_date
string
The start datetime of bank transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time
end_date
string
The end datetime of bank transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time
bank_transfer_id
string
Plaid’s unique identifier for a bank transfer.
account_id
string
The account ID to get events for all transactions to/from an account.
bank_transfer_type
string
The type of bank transfer. This will be either debit or credit. A debit indicates a transfer of money into your origination account; a credit indicates a transfer of money out of your origination account.

Possible values: debit, credit, null
event_types
[string]
Filter events by event type.

Possible values: pending, cancelled, failed, posted, reversed
count
integer
The maximum number of bank transfer events to return. If the number of events matching the above parameters is greater than count, the most recent events will be returned.

Default: 25
Maximum: 25
Minimum: 1
offset
integer
The offset into the list of bank transfer events. When count=25 and offset=0, the first 25 events will be returned. When count=25 and offset=25, the next 25 bank transfer events will be returned.

Default: 0
Minimum: 0
origination_account_id
string
The origination account ID to get events for transfers from a specific origination account.
direction
string
Indicates the direction of the transfer: outbound: for API-initiated transfers inbound: for payments received by the FBO account.

Possible values: inbound, outbound, null
Select group for content switcher
Select Language
1const request: BankTransferEventListRequest = {
2  start_date: start_date,
3  end_date: end_date,
4  bank_transfer_id: bank_transfer_id,
5  account_id: account_id,
6  bank_transfer_type: bank_transfer_type,
7  event_types: event_types,
8  count: count,
9  offset: offset,
10  origination_account_id: origination_account_id,
11  direction: direction,
12};
13try {
14  const response = await plaidClient.bankTransferEventList(request);
15  const events = response.data.bank_transfer_events;
16  for (const event of events) {
17    // iterate through events
18  }
19} catch (error) {
20  // handle error
21}
bank_transfer/event/list

Response fields and example

bank_transfer_events
[object]
event_id
integer
Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers.

Minimum: 0
timestamp
string
The datetime when this event occurred. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time
event_type
string
The type of event that this bank transfer represents.
pending: A new transfer was created; it is in the pending state.
cancelled: The transfer was cancelled by the client.
failed: The transfer failed, no funds were moved.
posted: The transfer has been successfully submitted to the payment network.
reversed: A posted transfer was reversed.

Possible values: pending, cancelled, failed, posted, reversed
account_id
string
The account ID associated with the bank transfer.
bank_transfer_id
string
Plaid’s unique identifier for a bank transfer.
origination_account_id
nullablestring
The ID of the origination account that this balance belongs to.
bank_transfer_type
string
The type of bank transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account.

Possible values: debit, credit
bank_transfer_amount
string
The bank transfer amount.
bank_transfer_iso_currency_code
string
The currency of the bank transfer amount.
failure_reason
nullableobject
The failure reason if the type of this transfer is "failed" or "reversed". Null value otherwise.
ach_return_code
nullablestring
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is reversed. For a full listing of ACH return codes, see Bank Transfers errors.
description
string
A human-readable description of the reason for the failure or reversal.
direction
nullablestring
Indicates the direction of the transfer: outbound for API-initiated transfers, or inbound for payments received by the FBO account.

Possible values: outbound, inbound, null
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "bank_transfer_events": [
3    {
4      "account_id": "6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B",
5      "bank_transfer_amount": "12.34",
6      "bank_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
7      "bank_transfer_iso_currency_code": "USD",
8      "bank_transfer_type": "credit",
9      "direction": "outbound",
10      "event_id": 1,
11      "event_type": "pending",
12      "failure_reason": null,
13      "origination_account_id": "",
14      "timestamp": "2020-08-06T17:27:15Z"
15    }
16  ],
17  "request_id": "mdqfuVxeoza6mhu"
18}
Was this helpful?

/bank_transfer/event/sync

Sync bank transfer events

/bank_transfer/event/sync allows you to request up to the next 25 Plaid-initiated bank transfer events that happened after a specific event_id. When using Auth with micro-deposit verification enabled, this endpoint can be used to fetch status updates on ACH micro-deposits. For more details, see micro-deposit events.

bank_transfer/event/sync

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
after_id
requiredinteger
The latest (largest) event_id fetched via the sync endpoint, or 0 initially.

Minimum: 0
count
integer
The maximum number of bank transfer events to return.

Default: 25
Minimum: 1
Maximum: 25
Select group for content switcher
Select Language
1const request: BankTransferEventListRequest = {
2  after_id: afterID,
3  count: 25,
4};
5try {
6  const response = await plaidClient.bankTransferEventSync(request);
7  const events = response.data.bank_transfer_events;
8  for (const event of events) {
9    // iterate through events
10  }
11} catch (error) {
12  // handle error
13}
bank_transfer/event/sync

Response fields and example

bank_transfer_events
[object]
event_id
integer
Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers.

Minimum: 0
timestamp
string
The datetime when this event occurred. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time
event_type
string
The type of event that this bank transfer represents.
pending: A new transfer was created; it is in the pending state.
cancelled: The transfer was cancelled by the client.
failed: The transfer failed, no funds were moved.
posted: The transfer has been successfully submitted to the payment network.
reversed: A posted transfer was reversed.

Possible values: pending, cancelled, failed, posted, reversed
account_id
string
The account ID associated with the bank transfer.
bank_transfer_id
string
Plaid’s unique identifier for a bank transfer.
origination_account_id
nullablestring
The ID of the origination account that this balance belongs to.
bank_transfer_type
string
The type of bank transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account.

Possible values: debit, credit
bank_transfer_amount
string
The bank transfer amount.
bank_transfer_iso_currency_code
string
The currency of the bank transfer amount.
failure_reason
nullableobject
The failure reason if the type of this transfer is "failed" or "reversed". Null value otherwise.
ach_return_code
nullablestring
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is reversed. For a full listing of ACH return codes, see Bank Transfers errors.
description
string
A human-readable description of the reason for the failure or reversal.
direction
nullablestring
Indicates the direction of the transfer: outbound for API-initiated transfers, or inbound for payments received by the FBO account.

Possible values: outbound, inbound, null
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "bank_transfer_events": [
3    {
4      "account_id": "6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B",
5      "bank_transfer_amount": "12.34",
6      "bank_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
7      "bank_transfer_iso_currency_code": "USD",
8      "bank_transfer_type": "credit",
9      "direction": "outbound",
10      "event_id": 1,
11      "event_type": "pending",
12      "failure_reason": null,
13      "origination_account_id": "",
14      "timestamp": "2020-08-06T17:27:15Z"
15    }
16  ],
17  "request_id": "mdqfuVxeoza6mhu"
18}
Was this helpful?

Webhooks

Updates are sent for Items that are linked using micro-deposits.

When an automated micro-deposit is created, Plaid sends a webhook upon successful verification. If verification does not succeed after seven days for an automated micro-deposit, Plaid sends a VERIFICATION_EXPIRED webhook. If you attempt to retrieve an automated micro-deposit Item before verification succeeds, you’ll receive a response with the HTTP status code 400 and a Plaid error code of PRODUCT_NOT_READY. For Same-Day micro-deposits, Plaid does not send AUTOMATICALLY_VERIFIED or VERIFICATION_EXPIRED webhooks, but you may instead use the BANK_TRANSFERS_EVENTS_UPDATE webhook to access the underlying ACH events of micro-deposits.

AUTOMATICALLY_VERIFIED

Fired when an Item is verified via automated micro-deposits. We recommend communicating to your users when this event is received to notify them that their account is verified and ready for use.

webhook_type
string
AUTH
webhook_code
string
AUTOMATICALLY_VERIFIED
account_id
string
The account_id of the account associated with the webhook
item_id
string
The item_id of the Item associated with this webhook, warning, or error
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "AUTH",
3  "webhook_code": "AUTOMATICALLY_VERIFIED",
4  "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
5  "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
6  "environment": "production"
7}
Was this helpful?

VERIFICATION_EXPIRED

Fired when an Item was not verified via automated micro-deposits after seven days since the automated micro-deposit was made.

webhook_type
string
AUTH
webhook_code
string
VERIFICATION_EXPIRED
item_id
string
The item_id of the Item associated with this webhook, warning, or error
account_id
string
The account_id of the account associated with the webhook
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "AUTH",
3  "webhook_code": "VERIFICATION_EXPIRED",
4  "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
5  "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
6  "environment": "production"
7}
Was this helpful?

BANK_TRANSFERS_EVENTS_UPDATE

Fired when new ACH events are available. To begin receiving this webhook, you must first register your webhook listener endpoint via the webhooks page in the Dashboard. The BANK_TRANSFERS_EVENTS_UPDATE webhook can be used to track the progress of ACH transfers used in micro-deposit verification. Receiving this webhook indicates you should fetch the new events from /bank_transfer/event/sync. Note that Transfer customers should use Transfer webhooks instead of using BANK_TRANSFERS_EVENTS_UPDATE; see micro-deposit events documentation for more details.

webhook_type
string
BANK_TRANSFERS
webhook_code
string
BANK_TRANSFERS_EVENTS_UPDATE
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "BANK_TRANSFERS",
3  "webhook_code": "BANK_TRANSFERS_EVENTS_UPDATE",
4  "environment": "production"
5}
Was this helpful?

transfer sending receiving funds

Sending and Receiving Funds

Learn how to send or receive funds

Sending funds overview

  1. Make sure you have already linked an Item, with /link/token/create initialized with the transfer product. For more details on linking Items, including on how to increase conversion by using a Payment Profile, see Transfer process overview.

  2. Determine the transfer failure risk of the Item by calling /transfer/authorization/create and providing the access_token.

  3. Check the authorization.decision. If it is declined, you cannot complete the transfer. If it is approved, check the authorization.decision_rationale field. If authorization.decision_rationale is null, proceed to the next step. If it is non-null, Plaid was unable to collect enough data to make a thorough risk evaluation; decide whether to proceed with creating the transfer based on your own risk assessment protocols.

  4. Create the transfer by calling /transfer/create using the authorization_id received in the previous step. Plaid will execute the transfer and automatically sweep funds into your account once they are available to be swept.

Determine the transfer failure risk

To determine the transfer failure risk, call the /transfer/authorization/create endpoint with the following:

  • Either the user's payment_profile_token, or (if you are not using a Payment Profile) the access_token and account_id that represents the account where you'd like to send funds to.

  • The amount (fund amount) you’re sending

  • type as credit if sending funds, or type as debit if receiving funds

  • ach_class as ppd for an personal account, or as ccd for a business account

  • user object with legal_name and other information (if you've specified ccd as the ach_class, you'll also need to specify the business’s name on the account within the user.legal_name parameter; if set to a person’s name it will be rejected).

For sample code and a sample response, see the /transfer/authorization/create API reference.

The response will contain an authorization object with details about the transfer authorization, including:

  • authorization.id, you'll need this to create the transfer in next step. This expires after 1 hour (unless your account has been approved for a longer expiration window) so you should persist this in a datastore.

  • authorization.decision, the decision from the authorization engine regarding the transfer. If this decision is "approved", you can proceed to the next step and create the transfer. If the decision is "declined", you will not be able to create the transfer (for more information on the decision and decision_rationale fields, see Transfer decision authorization).

Check the authorization.decision_rationale field before calling /transfer/create. If Plaid was unable to evaluate the risk of the transaction, this field will explain why. Transfer authorizations with a non-null decision_rationale field will be at higher risk of an ACH return and are not eligible for Guarantee.

Create the transfer

Create the transfer by calling the /transfer/create endpoint with the following:

  • The authorization_id of the transfer (returned from the previous step)

  • Either the user's payment_profile_token, or (if you are not using a Payment Profile) the access_token and account_id that represents the account you'd like to send funds to.

  • amount you’re sending

  • user object with legal_name and other information (if you've specified ccd as the ach_class, you'll also need to specify the business’s name on the account within the user.legal_name parameter; if set to a person’s name it will be rejected).

  • If reprocessing a returned transfer, please note that the description field must be "Retry" to indicate that it's a retry of a previously returned transfer. You may retry a transfer up to 2 times, within 180 days of creating the original transfer. Only transfers with return code R01 or R09 may be retried. For a full listing of ACH return codes, see Transfer errors.

Many of these parameters are the same as those specified when determining the transfer failure risk. This is in case you'd like to process an amount different from the amount that was authorized (only for amounts less than the original). For example, you may initially authorize for $100, but may only need to charge the user $90.

For sample code and a sample response, see the API reference for /transfer/create.

In the response is a transfer object. We recommend persisting the transfer.id in a datastore as you’ll need this when reconciling transactions or canceling a transaction.

To view the status of a transfer after it has been created, you can use the Dashboard or learn more about Transfer reconciliation.

Sample app code

For a real-life example of an app that incorporates the /transfer/authorization/create and /transfer/create endpoints, see the Node-based Plaid Pattern Transfer sample app. Pattern Transfer is a sample subscriptions payment app that enables ACH bank transfers. The Transfer create code can be found in transfers.js

auth partnerships square

Integrate Plaid with Square

Use Plaid and Square to accept ACH Payments


Plaid and Square have partnered together to offer businesses and developers an easier way to accept ACH payments. Square leverages Plaid Link to instantly authenticate a customer’s bank account. Plaid ensures businesses will not need to collect or provide any banking information on their own. Once an account is authenticated, any business can accept ACH Payments through Square’s Web Payments SDK and Square Invoices.

Why Square?

Square is a leader in payment solutions for small businesses, offering powerful tools to enable any business to send and receive payments. Square is enabling ACH via Web Payments SDK to help developers build innovative online payment experiences and via Square Invoices to help businesses accept flexible payment methods. ACH is ideal for businesses in professional services, wholesale, and other verticals where large transactions are common and getting paid remotely is essential. When you integrate Square with Plaid, Square will not charge for any fees associated with an ACH refund, helping simplify the costs and return risk of ACH.

Getting Started

This integration is designed for developers and businesses who have signed up for a Square account. As a developer, you will need to enable the Square Web Payment SDK into your application and create an application through the Square Quickstart project before enabling ACH. Once enabled, you will be able to access Plaid Link directly through the Square Web Payments SDK. As a business, you can accept ACH payments directly through Square Invoices without any additional integration work. For more information, please review Square’s API docs and sign up for a Square Account.

api accounts

Accounts

API reference for retrieving account information and seeing all possible account types and subtypes

/accounts/get

Retrieve accounts

The /accounts/get endpoint can be used to retrieve a list of accounts associated with any linked Item. Plaid will only return active bank accounts — that is, accounts that are not closed and are capable of carrying a balance. For items that went through the updated account selection pane, this endpoint only returns accounts that were permissioned by the user when they initially created the Item. If a user creates a new account after the initial link, you can capture this event through the NEW_ACCOUNTS_AVAILABLE webhook and then use Link's update mode to request that the user share this new account with you.
This endpoint retrieves cached information, rather than extracting fresh information from the institution. As a result, balances returned may not be up-to-date; for realtime balance information, use /accounts/balance/get instead. Note that some information is nullable.

accounts/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
options
object
An optional object to filter /accounts/get results.
account_ids
[string]
An array of account_ids to retrieve for the Account.
Select group for content switcher
Select Language
1const request: AccountsGetRequest = {
2  access_token: ACCESS_TOKEN,
3};
4try {
5  const response = await plaidClient.accountsGet(request);
6  const accounts = response.data.accounts;
7} catch (error) {
8  // handle error
9}
accounts/get

Response fields and example

accounts
[object]
An array of financial institution accounts associated with the Item. If /accounts/balance/get was called, each account will include real-time balance information.
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullablenumber
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullablenumber
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullablenumber
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullablestring
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
item
object
Metadata about the Item.
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
nullablestring
The Plaid Institution ID associated with the Item. Field is null for Items created via Same Day Micro-deposits.
webhook
nullablestring
The URL registered to receive webhooks for the Item.
error
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
available_products
[string]
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
billed_products
[string]
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available_products. Note - billed_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
products
[string]
A list of initialized products for the Item. In almost all cases, this will be the same as the billed_products field. For some products, it is possible for the product to be initialized on an Item but not yet billed (e.g. Assets, before /asset_report/create has been called), in which case the product may appear in products but not in billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consented_products
[string]
A list of products that have gone through consent collection for the Item. Only present for those enabled in the Data Transparency beta. If you are not enrolled in Data Transparency, this field is not used.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consent_expiration_time
nullablestring
The RFC 3339 timestamp after which the consent provided by the end user will expire. Upon consent expiration, the item will enter the ITEM_LOGIN_REQUIRED error state. To circumvent the ITEM_LOGIN_REQUIRED error and maintain continuous consent, the end user can reauthenticate via Link’s update mode in advance of the consent expiration time.
Note - This is only relevant for certain OAuth-based institutions. For all other institutions, this field will be null.

Format: date-time
update_type
string
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication.
background - Item can be updated in the background
user_present_required - Item requires user interaction to be updated

Possible values: background, user_present_required
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "accounts": [
3    {
4      "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
5      "balances": {
6        "available": 100,
7        "current": 110,
8        "iso_currency_code": "USD",
9        "limit": null,
10        "unofficial_currency_code": null
11      },
12      "mask": "0000",
13      "name": "Plaid Checking",
14      "official_name": "Plaid Gold Standard 0% Interest Checking",
15      "persistent_account_id": "8cfb8beb89b774ee43b090625f0d61d0814322b43bff984eaf60386e",
16      "subtype": "checking",
17      "type": "depository"
18    },
19    {
20      "account_id": "6PdjjRP6LmugpBy5NgQvUqpRXMWxzktg3rwrk",
21      "balances": {
22        "available": null,
23        "current": 23631.9805,
24        "iso_currency_code": "USD",
25        "limit": null,
26        "unofficial_currency_code": null
27      },
28      "mask": "6666",
29      "name": "Plaid 401k",
30      "official_name": null,
31      "subtype": "401k",
32      "type": "investment"
33    },
34    {
35      "account_id": "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58",
36      "balances": {
37        "available": null,
38        "current": 65262,
39        "iso_currency_code": "USD",
40        "limit": null,
41        "unofficial_currency_code": null
42      },
43      "mask": "7777",
44      "name": "Plaid Student Loan",
45      "official_name": null,
46      "subtype": "student",
47      "type": "loan"
48    }
49  ],
50  "item": {
51    "available_products": [
52      "balance",
53      "identity",
54      "payment_initiation",
55      "transactions"
56    ],
57    "billed_products": [
58      "assets",
59      "auth"
60    ],
61    "consent_expiration_time": null,
62    "error": null,
63    "institution_id": "ins_117650",
64    "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
65    "update_type": "background",
66    "webhook": "https://www.genericwebhookurl.com/webhook"
67  },
68  "request_id": "bkVE1BHWMAZ9Rnr"
69}
Was this helpful?

Account type schema

The schema below describes the various types and corresponding subtypes that Plaid recognizes and reports for financial institution accounts.

depository
string
An account type holding cash, in which funds are deposited. Supported products for depository accounts are: Auth (checking and savings types only), Balance, Transactions, Identity, Payment Initiation, Assets, and Investments (cash management type only).
checking
string
Checking account
savings
string
Savings account
hsa
string
Health Savings Account (US only) that can only hold cash
cd
string
Certificate of deposit account
money market
string
Money market account
paypal
string
PayPal depository account
prepaid
string
Prepaid debit card
cash management
string
A cash management account, typically a cash account at a brokerage
ebt
string
An Electronic Benefit Transfer (EBT) account, used by certain public assistance programs to distribute funds (US only)
credit
string
A credit card type account. Supported products for credit accounts are: Balance, Transactions, Identity, and Liabilities.
credit card
string
Bank-issued credit card
paypal
string
PayPal-issued credit card
loan
string
A loan type account. Supported products for loan accounts are: Balance, Liabilities, and Transactions.
auto
string
Auto loan
business
string
Business loan
commercial
string
Commercial loan
construction
string
Construction loan
consumer
string
Consumer loan
home equity
string
Home Equity Line of Credit (HELOC)
loan
string
General loan
mortgage
string
Mortgage loan
overdraft
string
Pre-approved overdraft account, usually tied to a checking account
line of credit
string
Pre-approved line of credit
student
string
Student loan
other
string
Other loan type or unknown loan type
investment
string
An investment account. Supported products for investment accounts are: Balance and Investments. In API versions 2018-05-22 and earlier, this type is called brokerage.
529
string
Tax-advantaged college savings and prepaid tuition 529 plans (US)
401a
string
Employer-sponsored money-purchase 401(a) retirement plan (US)
401k
string
Standard 401(k) retirement account (US)
403B
string
403(b) retirement savings account for non-profits and schools (US)
457b
string
Tax-advantaged deferred-compensation 457(b) retirement plan for governments and non-profits (US)
brokerage
string
Standard brokerage account
cash isa
string
Individual Savings Account (ISA) that pays interest tax-free (UK)
crypto exchange
string
Standard cryptocurrency exchange account
education savings account
string
Tax-advantaged Coverdell Education Savings Account (ESA) (US)
fixed annuity
string
Fixed annuity
gic
string
Guaranteed Investment Certificate (Canada)
health reimbursement arrangement
string
Tax-advantaged Health Reimbursement Arrangement (HRA) benefit plan (US)
hsa
string
Non-cash tax-advantaged medical Health Savings Account (HSA) (US)
ira
string
Traditional Individual Retirement Account (IRA) (US)
isa
string
Non-cash Individual Savings Account (ISA) (UK)
keogh
string
Keogh self-employed retirement plan (US)
lif
string
Life Income Fund (LIF) retirement account (Canada)
life insurance
string
Life insurance account
lira
string
Locked-in Retirement Account (LIRA) (Canada)
lrif
string
Locked-in Retirement Income Fund (LRIF) (Canada)
lrsp
string
Locked-in Retirement Savings Plan (Canada)
mutual fund
string
Mutual fund account
non-custodial wallet
string
A cryptocurrency wallet where the user controls the private key
non-taxable brokerage account
string
A non-taxable brokerage account that is not covered by a more specific subtype
other
string
An account whose type could not be determined
other annuity
string
An annuity account not covered by other subtypes
other insurance
string
An insurance account not covered by other subtypes
pension
string
Standard pension account
prif
string
Prescribed Registered Retirement Income Fund (Canada)
profit sharing plan
string
Plan that gives employees share of company profits
qshr
string
Qualifying share account
rdsp
string
Registered Disability Savings Plan (RSDP) (Canada)
resp
string
Registered Education Savings Plan (Canada)
retirement
string
Retirement account not covered by other subtypes
rlif
string
Restricted Life Income Fund (RLIF) (Canada)
roth
string
Roth IRA (US)
roth 401k
string
Employer-sponsored Roth 401(k) plan (US)
rrif
string
Registered Retirement Income Fund (RRIF) (Canada)
rrsp
string
Registered Retirement Savings Plan (Canadian, similar to US 401(k))
sarsep
string
Salary Reduction Simplified Employee Pension Plan (SARSEP), discontinued retirement plan (US)
sep ira
string
Simplified Employee Pension IRA (SEP IRA), retirement plan for small businesses and self-employed (US)
simple ira
string
Savings Incentive Match Plan for Employees IRA, retirement plan for small businesses (US)
sipp
string
Self-Invested Personal Pension (SIPP) (UK)
stock plan
string
Standard stock plan account
tfsa
string
Tax-Free Savings Account (TFSA), a retirement plan similar to a Roth IRA (Canada)
trust
string
Account representing funds or assets held by a trustee for the benefit of a beneficiary. Includes both revocable and irrevocable trusts.
ugma
string
'Uniform Gift to Minors Act' (brokerage account for minors, US)
utma
string
'Uniform Transfers to Minors Act' (brokerage account for minors, US)
variable annuity
string
Tax-deferred capital accumulation annuity contract
other
string
Other or unknown account type. Supported products for other accounts are: Balance, Transactions, Identity, and Assets.
Was this helpful?

Account type / product support matrix

The chart below indicates which products can be used with which account types. Note that some products can only be used with certain subtypes:

  • Auth and Signal require a debitable checking or savings depository account.
  • Liabilities does not support loan types other than student or mortgage.
  • Transactions does not support loan types other than student.
  • Investments does not support depository types other than cash management.

Also note that not all institutions support all products; for details on which products a given institution supports, use /institutions/get_by_id or look up the institution on the Plaid dashboard status page.

ProductDepositoryCreditInvestmentsLoanOther
Auth
Balance *
Transactions
Identity
Assets
Investments
Liabilities
Payment Initiation (UK and Europe)
Virtual Accounts (UK and Europe)
Transfer
Income (Bank Income flow)
Signal

* Investments holdings data is not priced intra-day.

Currency code schema

The following currency codes are supported by Plaid.

iso_currency_code
string
Plaid supports all ISO 4217 currency codes.
unofficial_currency_code
string
List of unofficial currency codes
ADA
string
Cardano
BAT
string
Basic Attention Token
BCH
string
Bitcoin Cash
BNB
string
Binance Coin
BTC
string
Bitcoin
BTG
string
Bitcoin Gold
BSV
string
Bitcoin Satoshi Vision
CNH
string
Chinese Yuan (offshore)
DASH
string
Dash
DOGE
string
Dogecoin
ETC
string
Ethereum Classic
ETH
string
Ethereum
GBX
string
Pence sterling, i.e. British penny
LSK
string
Lisk
NEO
string
Neo
OMG
string
OmiseGO
QTUM
string
Qtum
USDT
string
Tether
XLM
string
Stellar Lumen
XMR
string
Monero
XRP
string
Ripple
ZEC
string
Zcash
ZRX
string
0x
Was this helpful?

Investment transaction types schema

Valid values for investment transaction types and subtypes. Note that transactions representing inflow of cash will appear as negative amounts, outflow of cash will appear as positive amounts.

buy
string
Buying an investment
assignment
string
Assignment of short option holding
contribution
string
Inflow of assets into a tax-advantaged account
buy
string
Purchase to open or increase a position
buy to cover
string
Purchase to close a short position
dividend reinvestment
string
Purchase using proceeds from a cash dividend
interest reinvestment
string
Purchase using proceeds from a cash interest payment
long-term capital gain reinvestment
string
Purchase using long-term capital gain cash proceeds
short-term capital gain reinvestment
string
Purchase using short-term capital gain cash proceeds
sell
string
Selling an investment
distribution
string
Outflow of assets from a tax-advantaged account
exercise
string
Exercise of an option or warrant contract
sell
string
Sell to close or decrease an existing holding
sell short
string
Sell to open a short position
cancel
string
A cancellation of a pending transaction
cash
string
Activity that modifies a cash position
account fee
string
Fees paid for account maintenance
contribution
string
Inflow of assets into a tax-advantaged account
deposit
string
Inflow of cash into an account
dividend
string
Inflow of cash from a dividend
stock distribution
string
Inflow of stock from a distribution
interest
string
Inflow of cash from interest
legal fee
string
Fees paid for legal charges or services
long-term capital gain
string
Long-term capital gain received as cash
management fee
string
Fees paid for investment management of a mutual fund or other pooled investment vehicle
margin expense
string
Fees paid for maintaining margin debt
non-qualified dividend
string
Inflow of cash from a non-qualified dividend
non-resident tax
string
Taxes paid on behalf of the investor for non-residency in investment jurisdiction
pending credit
string
Pending inflow of cash
pending debit
string
Pending outflow of cash
qualified dividend
string
Inflow of cash from a qualified dividend
short-term capital gain
string
Short-term capital gain received as cash
tax
string
Taxes paid on behalf of the investor
tax withheld
string
Taxes withheld on behalf of the customer
transfer fee
string
Fees incurred for transfer of a holding or account
trust fee
string
Fees related to administration of a trust account
unqualified gain
string
Unqualified capital gain received as cash
withdrawal
string
Outflow of cash from an account
fee
string
Fees on the account, e.g. commission, bookkeeping, options-related.
account fee
string
Fees paid for account maintenance
adjustment
string
Increase or decrease in quantity of item
dividend
string
Inflow of cash from a dividend
interest
string
Inflow of cash from interest
interest receivable
string
Inflow of cash from interest receivable
long-term capital gain
string
Long-term capital gain received as cash
legal fee
string
Fees paid for legal charges or services
management fee
string
Fees paid for investment management of a mutual fund or other pooled investment vehicle
margin expense
string
Fees paid for maintaining margin debt
non-qualified dividend
string
Inflow of cash from a non-qualified dividend
non-resident tax
string
Taxes paid on behalf of the investor for non-residency in investment jurisdiction
qualified dividend
string
Inflow of cash from a qualified dividend
return of principal
string
Repayment of loan principal
short-term capital gain
string
Short-term capital gain received as cash
stock distribution
string
Inflow of stock from a distribution
tax
string
Taxes paid on behalf of the investor
tax withheld
string
Taxes withheld on behalf of the customer
transfer fee
string
Fees incurred for transfer of a holding or account
trust fee
string
Fees related to administration of a trust account
unqualified gain
string
Unqualified capital gain received as cash
transfer
string
Activity that modifies a position, but not through buy/sell activity e.g. options exercise, portfolio transfer
assignment
string
Assignment of short option holding
adjustment
string
Increase or decrease in quantity of item
exercise
string
Exercise of an option or warrant contract
expire
string
Expiration of an option or warrant contract
merger
string
Stock exchanged at a pre-defined ratio as part of a merger between companies
request
string
Request fiat or cryptocurrency to an address or email
send
string
Inflow or outflow of fiat or cryptocurrency to an address or email
spin off
string
Inflow of stock from spin-off transaction of an existing holding
split
string
Inflow of stock from a forward split of an existing holding
trade
string
Trade of one cryptocurrency for another
transfer
string
Movement of assets into or out of an account
Was this helpful?

identity verification hybrid input validation

Hybrid Input Validation

Identity Verification does as much as possible to ensure the user data it helps you collect and verify is clean and standardized. If you're getting all your user data for Identity Verification entirely from the Link flow, then you don't need to worry about the validations described below. If you are submitting data about the user via the API (e.g. for a hybrid or fully API-based verification approach), you will need to match the formatting and standardization requirements described below.

To help with development, we also provide a JSON file containing the same validation rules.

ID Numbers

Plaid's Lightning Verification will automatically collect, validate, and verify any of the following ID numbers for countries that you've enabled in the Dashboard Editor.

If you are separately collecting ID numbers outside of Link, or if you have existing customer data you're looking to import into Plaid, you can submit this data to the Identity Verification API programmatically via /identity_verification/create or the /link/token/create user object.

The table below lists each ID number that Identity Verification supports. The API type is a unique identifier that you should provide via API via the id_number.type field.

ID Numbers submitted via API should be stripped of any formatting characters like spaces, periods, and dashes. The table below also includes the exact regular expressions we use to decide whether a given ID Number is well-formed and valid for that region's ID type.

Need this data for your code? Download these validation rules in JSON form

CountryCountry CodeID NameAPI TypeFormat
ArgentinaARDocumento Nacional de Identidad (DNI)ar_dni\A\d{8,10}\z
AustraliaAUDriver’s Licenseau_drivers_license\A[A-Z0-9]{6,11}\z
AustraliaAUPassport Numberau_passport\A[A-Z0-9]{7,9}\z
BrazilBRCadastro de Pessoas Físicas (CPF)br_cpf\A\d{11}\z
CanadaCASocial Insurance Number (SIN)ca_sin\A\d{9}\z
ChileCLRol Único Nacional (RUN)cl_run\A\d{8}[A-Z\d]\z
ChinaCNResident Identity Card Numbercn_resident_card`\A\d{15}
ColombiaCONúmero de Identificación Tributaria (NIT)co_nit\A\d{8,10}\z
DenmarkDKCivil Personal Registration (CPR)dk_cpr\A\d{9,11}\z
EgyptEGNational ID Card Numbereg_national_id\A\d{14}\z
Hong KongHKHong Kong Identity (HKID)hk_hkid\A[A-Z0-9]{8,9}\z
IndiaINPermanent Account Number (PAN)in_pan\A[A-Z]{5}\d{4}[A-Z]\z
IndiaINVoter ID (EPIC)in_epic\A[A-Z]{3}\d{7}\z
ItalyITCodice Fiscale (CF)it_cf\A[A-Z]{6}\d{2}[A-Z]\d{2}[A-Z]\d{3}[A-Z]\z
JapanJP"My Number" Resident Record Codejp_my_number\A\d{12}\z
JordanJOCivil Identification Numberjo_civil_id\A\d{10,14}\z
KenyaKEHuduma Nambake_huduma_namba\A\d{10}\z
KuwaitKWCivil ID Card Numberkw_civil_id\A\d{12}\z
MalaysiaMYNational Registration Identity Card Number (NRIC)my_nric\A\d{12}\z
MexicoMXClave Única de Registro de Población (CURP)mx_curp\A[A-Z]{4}\d{6}[A-Z]{6}[A-Z\d]\d\z
MexicoMXRegistro Federal de Contribuyentes (RFC)mx_rfc\A[A-Z]{4}\d{6}[A-Z\d]{3}\z
New ZealandNZDriver’s Licensenz_drivers_license\A[A-Z]{2}\d{6}\z
NigeriaNGNational ID Numberng_nin\A[A-Z0-9]{11}\z
OmanOMIdentity Card Numberom_civil_id\A\d{8,9}\z
PhilippinesPHPhilSys Numberph_psn\A\d{12}\z
PolandPLPESEL Numberpl_pesel\A\d{11}\z
RomaniaROCod Numeric Personal (CNP)ro_cnp\A\d{13}\z
Saudi ArabiaSABiṭāgat Al-ʼaḥwālsa_national_id\A[A-Z0-9]{10}\z
SingaporeSGNational Registration Identity Cardsg_nric\A[A-Z]\d{7}[A-Z]\z
South AfricaZASmart ID Card Numberza_smart_id\A\d{13}\z
SpainESDocumento Nacional de Identidad (DNI)es_dni\A\d{8}[A-Z]\z
SpainESNúmero de Identidad de Extranjero (NIE)es_nie\A[A-Z]\d{7}[A-Z]\z
SwedenSEPersonnummer (PIN)se_pin\A\d{9,12}\z
TurkeyTRT.C. Kimlik No.tr_tc_kimlik\A\d{11}\z
United StatesUSSocial Security Number (SSN)us_ssn\A\d{9}\z
United StatesUSSocial Security Number (SSN) Last 4us_ssn_last_4\A\d{4}\z

Input Validation by Country

Address standards vary by country. Some countries do not support postal code or region (the equivalent of "state" or "province" depending on the region). In other countries, postal code and/or region is valid in a sense, but superfluous and not typically collected in native forms.

Separately, variations in identity data coverage mean that collection of "ID Number" is a required part of Lightning Verification in some countries, optional (configured in the Dashboard Editor) for other countries, and not supported in countries that do not support Lightning Verification at all.

This regional variation is reflected in the table below.

The labels for each input field below correspond to the following input validations:

  • address.postal_code and address.region

    • Required - If address is provided as part of the request, this field must always be present

    • Not Accepted - If address is provided as part of the request, this field must be omitted. Specifically, the key should be omitted from the address object (as opposed to the key being present with a null value)

  • id_number

    • Required - If id_number is not provided for this country, kyc_check will treat the Identity Verification Session as having incomplete data and will require user interaction with the Identity Verification modal in order to collect id_number

    • Optional - If id_number is not provided for this country and your Identity Verification Template is configured to not collect ID numbers for this country then Identity Verification will automatically run the kyc_check step without any user interaction as long as all other required input fields are provided. Similar to the address fields, the API requires you omit the id_number key entirely if you are not providing ID number data

    • Not Accepted - ID number verification is not supported for this country and the id_number field should always be omitted from API requests

Need this data for your code? Download these validation rules in JSON form

CountryCountry Codeaddress.postal_codeaddress.regionid_number
AfghanistanAFRequiredNot AcceptedNot Accepted
AlbaniaALRequiredNot AcceptedNot Accepted
AlgeriaDZRequiredNot AcceptedNot Accepted
AndorraADRequiredNot AcceptedNot Accepted
AngolaAONot AcceptedNot AcceptedNot Accepted
AnguillaAINot AcceptedNot AcceptedNot Accepted
Antigua & BarbudaAGNot AcceptedNot AcceptedNot Accepted
ArgentinaARRequiredRequiredRequired
ArmeniaAMRequiredNot AcceptedNot Accepted
ArubaAWNot AcceptedNot AcceptedNot Accepted
AustraliaAURequiredRequiredRequired
AustriaATRequiredNot AcceptedRequired
AzerbaijanAZRequiredNot AcceptedNot Accepted
BahamasBSNot AcceptedNot AcceptedNot Accepted
BahrainBHRequiredNot AcceptedNot Accepted
BangladeshBDRequiredNot AcceptedNot Accepted
BarbadosBBRequiredNot AcceptedNot Accepted
BelarusBYRequiredNot AcceptedNot Accepted
BelgiumBERequiredNot AcceptedRequired
BelizeBZNot AcceptedNot AcceptedNot Accepted
BeninBJNot AcceptedNot AcceptedNot Accepted
BermudaBMRequiredNot AcceptedNot Accepted
BhutanBTRequiredNot AcceptedNot Accepted
BoliviaBONot AcceptedNot AcceptedNot Accepted
Bosnia & HerzegovinaBARequiredNot AcceptedNot Accepted
BotswanaBWRequiredNot AcceptedNot Accepted
BrazilBRRequiredRequiredRequired
British Virgin IslandsVGRequiredNot AcceptedNot Accepted
BruneiBNRequiredNot AcceptedNot Accepted
BulgariaBGRequiredNot AcceptedNot Accepted
Burkina FasoBFNot AcceptedNot AcceptedNot Accepted
BurundiBIRequiredNot AcceptedNot Accepted
CambodiaKHRequiredNot AcceptedNot Accepted
CameroonCMRequiredNot AcceptedNot Accepted
CanadaCARequiredRequiredOptional
Cape VerdeCVRequiredNot AcceptedNot Accepted
Caribbean NetherlandsBQRequiredNot AcceptedNot Accepted
Cayman IslandsKYRequiredNot AcceptedNot Accepted
Central African RepublicCFRequiredNot AcceptedNot Accepted
ChadTDNot AcceptedNot AcceptedNot Accepted
ChileCLRequiredRequiredRequired
ChinaCNRequiredRequiredRequired
ColombiaCORequiredRequiredRequired
ComorosKMRequiredNot AcceptedNot Accepted
Congo - BrazzavilleCGRequiredNot AcceptedNot Accepted
Cook IslandsCKRequiredNot AcceptedNot Accepted
Costa RicaCRRequiredNot AcceptedNot Accepted
CroatiaHRRequiredNot AcceptedNot Accepted
CuraçaoCWNot AcceptedNot AcceptedNot Accepted
CyprusCYRequiredNot AcceptedNot Accepted
Czech RepublicCZRequiredNot AcceptedRequired
Côte d’IvoireCIRequiredNot AcceptedNot Accepted
DenmarkDKRequiredNot AcceptedRequired
DjiboutiDJNot AcceptedNot AcceptedNot Accepted
DominicaDMRequiredNot AcceptedNot Accepted
Dominican RepublicDORequiredNot AcceptedNot Accepted
EcuadorECRequiredNot AcceptedNot Accepted
EgyptEGRequiredRequiredNot Accepted
El SalvadorSVRequiredNot AcceptedNot Accepted
EritreaERRequiredNot AcceptedNot Accepted
EstoniaEERequiredNot AcceptedNot Accepted
EswatiniSZRequiredNot AcceptedNot Accepted
EthiopiaETRequiredNot AcceptedNot Accepted
Faroe IslandsFORequiredNot AcceptedNot Accepted
FijiFJNot AcceptedNot AcceptedNot Accepted
FinlandFIRequiredNot AcceptedRequired
FranceFRRequiredNot AcceptedRequired
French PolynesiaPFRequiredNot AcceptedNot Accepted
GabonGARequiredNot AcceptedNot Accepted
GambiaGMRequiredNot AcceptedNot Accepted
GeorgiaGERequiredNot AcceptedNot Accepted
GermanyDERequiredNot AcceptedRequired
GhanaGHNot AcceptedNot AcceptedNot Accepted
GibraltarGIRequiredNot AcceptedRequired
GreeceGRRequiredNot AcceptedNot Accepted
GreenlandGLRequiredNot AcceptedNot Accepted
GrenadaGDRequiredNot AcceptedNot Accepted
GuatemalaGTRequiredRequiredNot Accepted
GuernseyGGRequiredNot AcceptedNot Accepted
GuineaGNRequiredNot AcceptedNot Accepted
Guinea-BissauGWRequiredNot AcceptedNot Accepted
GuyanaGYRequiredNot AcceptedNot Accepted
HaitiHTRequiredNot AcceptedNot Accepted
HondurasHNRequiredNot AcceptedNot Accepted
Hong KongHKNot AcceptedRequiredRequired
HungaryHURequiredNot AcceptedNot Accepted
IcelandISRequiredNot AcceptedNot Accepted
IndiaINRequiredRequiredRequired
IndonesiaIDRequiredRequiredNot Accepted
IraqIQRequiredNot AcceptedNot Accepted
IrelandIERequiredRequiredRequired
Isle of ManIMRequiredNot AcceptedNot Accepted
IsraelILRequiredNot AcceptedNot Accepted
ItalyITRequiredRequiredOptional
JamaicaJMNot AcceptedNot AcceptedNot Accepted
JapanJPRequiredRequiredOptional
JerseyJERequiredNot AcceptedNot Accepted
JordanJORequiredNot AcceptedNot Accepted
KazakhstanKZRequiredNot AcceptedNot Accepted
KenyaKERequiredNot AcceptedRequired
KiribatiKIRequiredNot AcceptedNot Accepted
KosovoXKRequiredNot AcceptedNot Accepted
KuwaitKWRequiredNot AcceptedNot Accepted
KyrgyzstanKGRequiredNot AcceptedNot Accepted
LaosLARequiredNot AcceptedNot Accepted
LatviaLVRequiredNot AcceptedNot Accepted
LebanonLBRequiredNot AcceptedNot Accepted
LesothoLSRequiredNot AcceptedNot Accepted
LiberiaLRRequiredNot AcceptedNot Accepted
LiechtensteinLIRequiredNot AcceptedNot Accepted
LithuaniaLTRequiredNot AcceptedNot Accepted
LuxembourgLURequiredNot AcceptedRequired
Macao SAR ChinaMORequiredNot AcceptedNot Accepted
MadagascarMGRequiredNot AcceptedNot Accepted
MalawiMWNot AcceptedNot AcceptedNot Accepted
MalaysiaMYRequiredRequiredRequired
MaldivesMVRequiredNot AcceptedNot Accepted
MaliMLNot AcceptedNot AcceptedNot Accepted
MaltaMTRequiredNot AcceptedNot Accepted
MauritaniaMRRequiredNot AcceptedNot Accepted
MauritiusMURequiredNot AcceptedNot Accepted
MexicoMXRequiredRequiredRequired
MoldovaMDRequiredNot AcceptedNot Accepted
MonacoMCRequiredNot AcceptedNot Accepted
MongoliaMNRequiredNot AcceptedNot Accepted
MontenegroMERequiredNot AcceptedNot Accepted
MontserratMSRequiredNot AcceptedNot Accepted
MoroccoMARequiredNot AcceptedNot Accepted
MozambiqueMZRequiredNot AcceptedNot Accepted
Myanmar (Burma)MMRequiredNot AcceptedNot Accepted
NamibiaNARequiredNot AcceptedNot Accepted
NauruNRRequiredNot AcceptedNot Accepted
NepalNPRequiredNot AcceptedNot Accepted
NetherlandsNLRequiredNot AcceptedRequired
New ZealandNZRequiredRequiredOptional
NicaraguaNIRequiredNot AcceptedNot Accepted
NigerNERequiredNot AcceptedNot Accepted
NigeriaNGRequiredRequiredRequired
NiueNURequiredNot AcceptedNot Accepted
North MacedoniaMKRequiredNot AcceptedNot Accepted
NorwayNORequiredNot AcceptedRequired
OmanOMRequiredNot AcceptedNot Accepted
PakistanPKRequiredNot AcceptedNot Accepted
Palestinian TerritoriesPSRequiredNot AcceptedNot Accepted
PanamaPANot AcceptedRequiredNot Accepted
Papua New GuineaPGRequiredNot AcceptedNot Accepted
ParaguayPYRequiredNot AcceptedNot Accepted
PeruPERequiredRequiredNot Accepted
PhilippinesPHRequiredRequiredOptional
PolandPLRequiredNot AcceptedOptional
PortugalPTRequiredRequiredRequired
QatarQANot AcceptedNot AcceptedNot Accepted
RomaniaRORequiredRequiredNot Accepted
RussiaRURequiredRequiredNot Accepted
RwandaRWRequiredNot AcceptedNot Accepted
SamoaWSRequiredNot AcceptedNot Accepted
San MarinoSMRequiredNot AcceptedNot Accepted
Saudi ArabiaSARequiredNot AcceptedNot Accepted
SenegalSNRequiredNot AcceptedNot Accepted
SerbiaRSRequiredNot AcceptedNot Accepted
SeychellesSCRequiredNot AcceptedNot Accepted
Sierra LeoneSLNot AcceptedNot AcceptedNot Accepted
SingaporeSGRequiredNot AcceptedRequired
SlovakiaSKRequiredNot AcceptedRequired
SloveniaSIRequiredNot AcceptedNot Accepted
Solomon IslandsSBRequiredNot AcceptedNot Accepted
SomaliaSORequiredNot AcceptedNot Accepted
South AfricaZARequiredRequiredRequired
South KoreaKRRequiredRequiredNot Accepted
South SudanSSNot AcceptedNot AcceptedNot Accepted
SpainESRequiredRequiredOptional
Sri LankaLKRequiredNot AcceptedNot Accepted
St. Kitts & NevisKNRequiredNot AcceptedNot Accepted
St. LuciaLCRequiredNot AcceptedNot Accepted
St. MartinMFRequiredNot AcceptedNot Accepted
St. Vincent & GrenadinesVCRequiredNot AcceptedNot Accepted
SudanSDRequiredNot AcceptedNot Accepted
SurinameSRRequiredNot AcceptedNot Accepted
SwedenSERequiredNot AcceptedRequired
SwitzerlandCHRequiredNot AcceptedRequired
São Tomé & PríncipeSTRequiredNot AcceptedNot Accepted
TaiwanTWRequiredNot AcceptedNot Accepted
TajikistanTJRequiredNot AcceptedNot Accepted
TanzaniaTZRequiredNot AcceptedNot Accepted
ThailandTHRequiredRequiredNot Accepted
Timor-LesteTLRequiredNot AcceptedNot Accepted
TogoTGNot AcceptedNot AcceptedNot Accepted
TongaTONot AcceptedNot AcceptedNot Accepted
Trinidad & TobagoTTNot AcceptedNot AcceptedNot Accepted
TunisiaTNRequiredNot AcceptedNot Accepted
TurkeyTRRequiredNot AcceptedRequired
TurkmenistanTMRequiredNot AcceptedNot Accepted
Turks & Caicos IslandsTCRequiredNot AcceptedNot Accepted
TuvaluTVNot AcceptedNot AcceptedNot Accepted
UgandaUGNot AcceptedNot AcceptedNot Accepted
UkraineUARequiredNot AcceptedNot Accepted
United Arab EmiratesAENot AcceptedRequiredNot Accepted
United KingdomGBRequiredNot AcceptedRequired
United StatesUSRequiredRequiredOptional
UruguayUYRequiredNot AcceptedNot Accepted
UzbekistanUZRequiredNot AcceptedNot Accepted
VanuatuVUNot AcceptedNot AcceptedNot Accepted
Vatican CityVARequiredNot AcceptedNot Accepted
VenezuelaVERequiredNot AcceptedNot Accepted
VietnamVNRequiredNot AcceptedNot Accepted
Western SaharaEHRequiredNot AcceptedNot Accepted
YemenYENot AcceptedNot AcceptedNot Accepted
ZambiaZMRequiredNot AcceptedNot Accepted
ZimbabweZWNot AcceptedNot AcceptedNot Accepted

auth partnerships

Auth Payment Partners

Find payment providers who have partnered with Plaid to provide general purpose ACH money movement

Overview

Many Plaid developers choose to use a Plaid partner to move money with Auth. You will use Plaid Link initialized with the Auth product, but instead of using Plaid Auth endpoints, you will use endpoints from the payment platform, giving you access to payment functionality while freeing you from having to securely store sensitive bank account information.

The following is a list of payments platforms who have partnered with Plaid to provide ACH money movement via a special processor token, along with instructions on how to enable those integrations.

PartnerDescription
DwollaInstantly authenticate your customers' bank accounts for use with Dwolla's ACH API
SquareInstantly authenticate your customers' bank accounts for use with the Square Web Payments SDK
ACHQInstantly authenticate your customers' bank accounts for use with ACHQ's ACH API
AdyenValidate bank accounts and reduce returns through an end-to-end pay-with-your-bank solution with Adyen
AlpacaUse Alpaca with Plaid Auth to send and receive payments
Apex Fintech SolutionsInstantly authenticate your investors’ bank accounts for use with Apex Fintech Solutions Cash API
AstraInstantly authenticate your customer’s bank accounts for automated ACH transfers through the Astra platform
AtomicInstantly authenticate your customers' bank accounts to seamlessly fund investment accounts
BondInstantly authenticate your customers’ bank accounts for use with Bond’s ACH Transfers API
CheckCheck lets you embed payroll in your product and easily configure and authenticate direct deposit payments
CheckbookInstantly authenticate your customers’ bank accounts for use with Checkbook’s payment solution -- including ACH, real-time payments, push to card, virtual cards, and checks
Checkout.comInstantly authenticate bank account details for use with Checkout.com’s Unified Payments API, and unlock unrivaled payment performance
CircleCircle helps you accept payments that settle in digital dollar stablecoins - the next generation money tech stack
DriveWealthEnable your customers to instantly and securely fund DriveWealth supported investment accounts by linking their bank account with Plaid
Fortress TrustInstantly allow end customers to connect, verify and authorize funding to their Fortress Trust account from their external bank accounts
GalileoInstantly authenticate your customers' bank accounts for account opening and funding
GustoBuild payroll with Gusto, then use Plaid Auth to instantly connect your customers’ bank accounts and run payroll faster
HighnoteInstantly authenticate your customer’s bank accounts for use with the Highnote Platform to store account details, transfer funds, and make payments
LithicInstant bank authentication for ACH payments and card loads
MarqetaIntegrate Plaid and Marqeta’s APIs to seamlessly authenticate your customer’s bank account prior to an ACH transfer
Modern TreasuryInstantly authenticate your customers' bank accounts for use with Modern Treasury's ACH API
MoovInstantly authenticate your customers’ bank accounts to enable them to accept, store, and disburse funds with Moov
Prime TrustInstantly authenticate your customers' bank accounts for use with Prime Trust's account access API
RizeUse Plaid to instantly verify and connect your customers’ external bank accounts for use within the Rize Platform
Sila MoneyBanking, Digital Wallets, and ACH Payments API for software teams
Silicon Valley BankInstantly authenticate your customers' bank accounts for use with Silicon Valley Bank's ACH API
SolidInstantly authenticate external bank accounts for use with the Solid Platform
StripeInstantly authenticate your customers' bank accounts for use with Stripe's ACH API
Treasury PrimeSend payments and create counterparties with the Treasury Prime API
UnitInstantly authenticate counterparties’ bank accounts for use with the Unit API
VestaStreamline ACH onboarding flows and eliminate losses through Vesta’s payment guarantee for every approved transaction
VoPayEliminate inefficiencies of US and Canadian online bank account payments with VoPay’s EFT / ACH and Plaid

For more information, see the full list of partners in the Developer Dashboard.

Global payments options

Money movement via Plaid partners is only available for financial institutions within the US (with multiple providers above) and Canada (with VoPay). In Europe, Payment Initiation provides an easy and secure way to transfer funds.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js.

For a tutorial walkthrough of creating a similar app, see Account funding tutorial.

auth coverage microdeposit events

Micro-deposit events

Learn how to use Bank Transfers webhooks to receive micro-deposit status updates

Overview

If you are using the optional Same Day Micro-deposits verification flow for Auth and want to receive updates on the state of your micro-deposit transfers, you can enable webhooks for Bank Transfer events that notify you of transfer status updates for Plaid-initiated transfers within the ACH network.

Bank Transfers webhooks

To enable Bank Transfers webhooks, add your endpoint on the account webhooks page of the dashboard. If you are not able to access the page, contact your Plaid Account Manager.

Bank Transfers webhooks are not part of Plaid's Transfer product. All Auth customers have access to Bank Transfer webhooks; it is not required to sign up for Plaid Transfer to use these webhooks.

To confirm that your endpoint has been correctly configured, you can trigger a test webhook via /sandbox/bank_transfer/fire_webhook. You should receive the payload body specified below.

1{
2  "webhook_type": "BANK_TRANSFERS",
3  "webhook_code": "BANK_TRANSFERS_EVENTS_UPDATE"
4}

Once you have enabled Bank Transfers webhooks, the /bank_transfer/event/sync endpoint can be called to discover new ACH events. To know when you should call this endpoint, listen for the BANK_TRANSFERS_EVENTS_UPDATE webhook. You will receive a Bank Transfers webhook any time you have posted or returned ACH micro-deposit events available.

Bank transfers endpoints will only provide data about ACH events initiated through Plaid. They do not fire for other ACH activity on a linked account.

Event types

Once your user successfully completes the micro-deposit Link flow, you will receive an account_id in the success callback. Bank Transfers events also contain an account_id, which you should use to connect events to the corresponding user.

Pending

A pending event type means that we have a record of the micro-deposit in our systems, but it has not yet been sent. You may assume that micro-deposits are in a pending state once you exchange the corresponding Item’s public token for an access token. Note that Plaid does not send webhooks for new pending events, but you will still see pending events in event sync responses.

1{
2  "account_id": "3MqrrrP5pWUGgmnvaQlPu19R6DvwPRHwNbLr9",
3  "bank_transfer_amount": "0.52",
4  "bank_transfer_id": "5645fe0e-bd5e-d8da-828b-e2c7540c69d8",
5  "bank_transfer_iso_currency_code": "USD",
6  "bank_transfer_type": "credit",
7  "direction": "outbound",
8  "event_id": 5,
9  "event_type": "pending",
10  "failure_reason": null,
11  "origination_account_id": null,
12  "receiver_details": null,
13  "timestamp": "2021-03-22T18:52:02Z"
14}

No action needed

Posted

For successful micro-deposit transfers, posted events are the terminal event type, and no more events will be issued. Note that the end user may not receive the micro-deposit until several banking hours after the posted event. In addition, a posted event does not guarantee that the micro-deposit was successful; if the micro-deposit fails, a reversed event will eventually occur some time after the posted event.

1{
2  "account_id": "3MqrrrP5pWUGgmnvaQlPu19R6DvwPRHwNbLr9",
3  "bank_transfer_amount": "0.08",
4  "bank_transfer_id": "5645fe0e-bd5e-d8da-828b-e2c7540c69d8",
5  "bank_transfer_iso_currency_code": "USD",
6  "bank_transfer_type": "credit",
7  "direction": "outbound",
8  "event_id": 5,
9  "event_type": "posted",
10  "failure_reason": null,
11  "origination_account_id": null,
12  "receiver_details": null,
13  "timestamp": "2021-03-22T18:52:02Z"
14}

If the micro-deposit succeeds, all posted transfers will land in the end user’s account by 8:30am EST on the following banking day.

After the micro-deposit settlement time, Plaid recommends sending the end user an alert (through SMS, email, or push notification) to verify the micro-deposit amounts.

Reversed

A reversed event indicates that a micro-deposit attempt has failed. Reversed events will contain an ACH return code that indicates why the micro-deposit failed.

1{
2  "account_id": "bV8WNn73rLI5Ln1MmdErsDn9jv7w37uGMaQvP",
3  "bank_transfer_amount": "0.32",
4  "bank_transfer_id": "826712b2-c707-cf98-5ba9-13bd3cc2b2f0",
5  "bank_transfer_iso_currency_code": "USD",
6  "bank_transfer_type": "credit",
7  "direction": "outbound",
8  "event_id": 5,
9  "event_type": "reversed",
10  "failure_reason": {
11    "ach_return_code": "R03",
12    "description": "No account or unable to locate account"
13  },
14  "origination_account_id": null,
15  "receiver_details": null,
16  "timestamp": "2021-03-25T21:35:47Z"
17}

Contact the user with a notification that authentication has failed. Once they return to your application, restart the Link flow to begin another authentication attempt.

identity verification link

Link callbacks

Guide to using Link callbacks in your integration

After integrating Identity Verification using Link, you can use Link’s client-side callbacks to see how your users are progressing through the flow. Note that you will not be able to access these if you use the Plaid-hosted flow with shareable links.

onSuccess will fire when a user has successfully completed the Link flow. The link_session_id returned by onSuccess can be passed to /identity_verification/get in the identity_verification_id field to retrieve data on the verification. Note that receiving onSuccess simply means that the user completed the Identity Verification flow, not that their identity was verified. A completed session in which a user fails Identity Verification will still result in onSuccess.

onExit will fire when a user exits a session without finishing all required steps. If you receive this event, you may want to provide an option for the user to restart the Link flow, and/or provide guidance on manually performing KYC.

onEvent will fire at certain points throughout the IDV flow with updates on the user’s progress at each point. For each step, Plaid will send an IDENTITY_VERIFICATION_START_STEP event as well as a IDENTITY_VERIFICATION_PASS_STEP or IDENTITY_VERIFICATION_FAIL_STEP event based on the outcome of the step. Each step will also have an associated view_name. The possible view names include: ACCEPT_TOS, VERIFY_SMS,KYC_CHECK, DOCUMENTARY_VERIFICATION, RISK_CHECK, and SELFIE_CHECK.

For each session, Plaid will also inform you of the outcome of the session by sending an IDENTITY_VERIFICATION_PASS_SESSION or IDENTITY_VERIFICATION_FAIL_SESSION event based on the outcome of the session.

Note that, aside from IDENTITY_VERIFICATION_PASS_SESSION and IDENTITY_VERIFICATION_FAIL_SESSION, the sequence of view names and onEvent events are subject to change without notice, as Plaid adds additional functionality and makes improvements to flows. You should treat view names as informational and not rely on them for critical business logic.

auth partnerships modern treasury

Add Modern Treasury to your app

Use Modern Treasury with Plaid Auth to send and receive payments!

Partnership Modern Treasury logo

Overview

Plaid and Modern Treasury have partnered to offer businesses a secure and streamlined way to manage payment operations. Plaid enables businesses to instantly authenticate a counter-party’s bank account. With the Modern Treasury API, teams can initiate payments via ACH, Wire, and RTP through a single implementation. Modern Treasury’s solution supports the full cycle of money movement for growing businesses including payment initiation, approvals, monitoring, and reconciliation. As part of the integration, Modern Treasury customers can utilize Plaid’s APIs for real-time balance information.

With the Plaid + Modern Treasury integration, counter-parties can onboard with ease by verifying their accounts in seconds using Plaid Link, a drop-in front-end module. Plaid Link handles input validation, error handling, and multi-factor authentication, providing a seamless onboarding experience to users of the Modern Treasury web portal.

To get started sign up for Plaid API keys.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Modern Treasury account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Modern Treasury processor_token, which allows you to quickly and securely verify a bank funding source via Modern Treasury's API without having to store any sensitive banking information. Utilizing Plaid + Modern Treasury enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Modern Treasury in order to use the Plaid + Modern Treasury integration. You'll also need to enable your Plaid account for the Modern Treasury integration.

First, you will need to work with the Modern Treasury team to sign up for a Modern Treasury account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Modern Treasury to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Modern Treasury processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Modern Treasury, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Modern Treasury processor_token. You'll send this token to Modern Treasury and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Modern Treasury processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'modern_treasury',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Modern Treasury Production credentials prior to initiating live payment transactions in the Modern Treasury API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

sandbox institutions

Sandbox institutions

View institutions and institution test configurations available in the Sandbox

Institution details

All of the institutions that are available in the Plaid Development and Production environments are also available in the Sandbox. Plaid provides several Sandbox-only institutions to write integration tests against:

Institution nameID
First Platypus Bankins_109508
First Gingham Credit Unionins_109509
Tattersall Federal Credit Unionins_109510
Tartan Bankins_109511
Houndstooth Bankins_109512
Tartan-Dominion Bank of Canadains_43
Flexible Platypus Open Banking (UK Bank)ins_116834
Royal Bank of Plaid (UK Bank)ins_117650
Platypus OAuth Bank (for OAuth testing only)ins_127287
First Platypus OAuth App2App Bank (for App-to-App OAuth testing)ins_132241
Flexible Platypus Open Banking (for OAuth QR code authentication testing)ins_117181
Unhealthy Platypus Bank - Degradedins_132363
Unhealthy Platypus Bank - Downins_132361
Unsupported Platypus Bank - Institution Not Supportedins_133402
Platypus Bank RUX Auth (for RUX Pre-authenticated testing)ins_133502
Platypus Bank RUX Match (for RUX Pre-matched testing)ins_133503

All Sandbox institutions can be accessed using the Sandbox test credentials.

Note that when testing OAuth in Sandbox, the OAuth flow for Platypus will be shown instead of institution-specific flows.

None of the institutions in the list above use OAuth flows except for those that are explicitly marked as OAuth or European / UK institutions.

Institution details for Auth testing

You can trigger specific Auth flows in the Sandbox environment by using the following values. For detailed instructions on testing Auth in the Sandbox, see Testing Auth in the Sandbox.

StepInstant MatchAutomated Micro-depositsSame-Day Micro-deposits
InstitutionHoundstooth BankHoundstooth BankN/A
Usernameuser_gooduser_goodN/A
Passwordpass_goodmicrodeposits_goodN/A
AccountPlaid Saving (****1111)Plaid Checking (****0000)Checking or Savings
Routing number021000021021000021110000000
Account number111122223333111111112222333300001111222233330000
Micro-deposit #1N/AN/A $0.01
Micro-deposit #2N/AN/A $0.02
Wait before Sandbox verificationInstantAbout 24 hoursVerify interactively within minutes

investments

Introduction to Investments

View holdings and transactions from investment accounts

Explore API

Overview

The Investments product allows you to obtain holding, security, and transactions data for investment-type accounts in financial institutions within the United States and Canada. This data can be used for personal financial management tools and wealth management analysis.

Securities and holdings

The /investments/holdings/get endpoint provides both security data and holding data. Security data represents information about a specific security, such as its name, ticker symbol, and price. Security data is not specific to a user's account; any user who held the same security at the same financial institution at the same time would have identical security data.

1{
2  "close_price": 10.42,
3  "close_price_as_of": null,
4  "cusip": "258620103",
5  "institution_id": null,
6  "institution_security_id": null,
7  "is_cash_equivalent": false,
8  "isin": "US2586201038",
9  "iso_currency_code": "USD",
10  "name": "DoubleLine Total Return Bond Fund",
11  "proxy_security_id": null,
12  "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
13  "sedol": null,
14  "ticker_symbol": "DBLTX",
15  "type": "mutual fund",
16  "unofficial_currency_code": null
17}

Holding data, by contrast, represents information about a user's specific ownership of that security, such as the number of shares owned and the cost basis. Each holding includes a security_id field that can be cross-referenced to a security for more detailed information about the security itself.

1{
2  "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
3  "cost_basis": 10,
4  "institution_price": 10.42,
5  "institution_price_as_of": null,
6  "institution_value": 20.84,
7  "iso_currency_code": "USD",
8  "quantity": 2,
9  "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
10  "unofficial_currency_code": null
11}

Transactions

The /investments/transactions/get endpoint provides up to 24 months of investment transactions data. The schema for investment transactions is not the same as for transactions data returned by the Transactions product, instead providing securities-specific information. Inflow, such as stock sales, is shown as a negative amount, and outflow, such as stock purchases, is positive. The /investments/transactions/get endpoint can only be used for investment-type accounts; for obtaining transaction history for other account types, use Transactions.

1{
2  "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
3  "amount": -8.72,
4  "cancel_transaction_id": null,
5  "date": "2020-05-29",
6  "fees": 0,
7  "investment_transaction_id": "oq99Pz97joHQem4BNjXECev1E4B6L6sRzwANW",
8  "iso_currency_code": "USD",
9  "name": "INCOME DIV DIVIDEND RECEIVED",
10  "price": 0,
11  "quantity": 0,
12  "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ",
13  "subtype": "dividend",
14  "type": "cash",
15  "unofficial_currency_code": null
16}

Investments updates and webhooks

Investments data is not static, since users' holdings will change as they trade and as market prices fluctuate. Plaid typically checks for updates to investment data overnight, after market hours. There are two webhooks that are used for informing you of changes to investment data. The DEFAULT_UPDATE webhook of type HOLDINGS fires when new holdings have been detected or the quantity or price of an existing holding has changed. The DEFAULT_UPDATE webhook of type INVESTMENTS_TRANSACTIONS fires when a new or canceled investment transaction has been detected.

Unlike Transactions, Investments does not have a webhook to indicate when initial transaction data has loaded. Instead, if transactions data is not ready when /investments/transactions/get is first called, Plaid will wait for the data. For this reason, calling /investments/transactions/get immediately after Link may take up to one to two minutes to return.

Testing Investments

Investments can be tested in Sandbox or Development without any additional permissions.

Next steps

To get started building with Investments, see Add Investments to your App.

If you're ready to launch to Production, see the Launch checklist.

auth coverage testing

Testing Auth flows

Testing Instant Match, Automated Micro-deposit, and Same-Day Micro-deposit flows

Sandbox configuration

To test in the Sandbox environment, you need to set the Link configuration environment to "sandbox":

1Plaid.create({
2  // ...
3  env: 'sandbox',
4});

You will also want to direct any backend API requests to the sandbox URL:

1https://sandbox.plaid.com

Testing Instant Match

Test credentials
Sandbox inputSuccessful credentialsErroneous credentials
Institution NameHoundstooth Bank (ins_109512)––
Usernameuser_good––
Passwordpass_good––
Account SelectionPlaid Savings (****1111)––
Routing number021000021Any other routing number
Account number1111222233331111Any other account number
Testing the Link flow
  • Search for “Houndstooth Bank” in Link.
  • Enter user_good and pass_good in the Credential pane.
  • Select the second account that is returned: Plaid Savings (****1111).
  • In the Routing number input, enter: 021000021
  • In the Account number input, enter: 1111222233331111
  • Link will display the success view – click continue to trigger the onSuccess callback with a public_token.

Testing Automated Micro-deposits

Note that micro-deposit-based flows cannot be tested in the Development environment. To test this flow, use either Sandbox (using the instructions below) or Production. You can also test this with no code by using the Link Demo

Test credentials
Sandbox inputSuccessful credentialsErroneous credentials
Institution NameHoundstooth Bank (ins_109512)––
Usernameuser_good––
Passwordmicrodeposits_good––
Account SelectionPlaid Checking (****0000)––
Routing number021000021Any other routing number
Account number1111222233330000Any other account number
Testing the Link flow
  • Search for “Houndstooth Bank” in Link.
  • Enter user_good and microdeposits_good in the Credential pane.
  • Select the first account that is returned: Plaid Checking (****0000)
  • In the Routing number input, enter: 021000021
  • In the Account number input, enter: 1111222233330000
  • Enter your legal first and last name.
  • Link will display the Automated Micro-deposit success view – click continue to trigger the onSuccess callback with a public_token.

The micro-deposit verification will automatically succeed after twenty-four hours. To test a failed micro-deposit, or to skip the twenty-four hour waiting period, use the /sandbox/item/set_verification_status endpoint to manually control the Item's micro-deposit verification status.

Testing Same Day Micro-deposits

Note that micro-deposit-based flows cannot be tested in the Development environment. To test this flow, use either Sandbox (using the instructions below) or Production. You can also test this with no code by using the Link Demo

Test credentials
Sandbox inputSuccessful credentialsErroneous credentials
Routing number110000000Any other routing number
Account number1111222233330000Any other account number
Deposit codeABCAny other value
Initiating micro-deposits in Link
  • If you have configured Same Day Micro-deposits at failure points in Link, search for an institution that is not yet supported: "XYZ", click on Link with account numbers
  • If you have configured Same Day Micro-deposits with Auth Type Select, choose "Manually" from the menu
  • In the Routing number input, enter: 110000000
  • If you have configured Same Day Micro-deposits with Reroute to Credentials, choose the "Enter account number instead" option.
  • In the Account number input, enter: 1111222233330000
  • Select “checking” or “savings” as the account type
  • Link will display the success view – click Continue to trigger the onSuccess callback with a public_token
Verifying micro-deposits in Link
  • Call /item/public_token/exchange with your public_token from the previous step to receive an access_token.
  • Call /link/token/create and provide the access_token from the previous step to receive a link_token.
  • Open Link with your link_token.
  • In the deposit code, enter ABC
  • You have successfully verified your micro-deposits – click Continue to close Link successfully.

Testing micro-deposit events

Micro-deposits that are generated in Sandbox will never be posted by default. In order to generate a posted event that you can see when you query /bank_transfer/event/sync, you can use the /sandbox/bank_transfer/simulate endpoint.

Simulating a posted event in Sandbox does not generate a webhook. You will need to call /sandbox/bank_transfer/fire_webhook each time you want a webhook to be published for testing.

link messaging

Link messaging

Shape your messaging around Link to optimize conversion and user experience

Overview

Factors that you control, such as how Link is placed in your onboarding flow, and the UI of the page where it is hosted, can have large impacts on Link conversion. This article outlines best practices for Link presentation that you can adopt to maximize conversion and overall user experience.

Pre-Link messaging best practices

Explain the benefit to the user

Your UI should tell the user why they want to use Link. For example, linking an account might let them make free transfers, versus having to pay a credit card transaction fee. Or it might be faster, allowing them to avoid manual data entry of balances or transactions, or having to wait several days for a micro-deposit-based verification flow.

Tell the user what to expect

Before launching the Link flow, explain to the user that they'll be prompted to link a bank account with Plaid. Explain what data your app will be collecting from their account, and why it's needed.

Present Link as the default

Rather than presenting Link and manual flows as equal alternatives, encourage your customers to use Link through the size, positioning, and color of the Link entry point. You can also use labels such as "Recommended" or "Preferred". Yet another option is to display manual flows as an option only after the onExit callback (indicating a failed link attempt) has been received.

Explain that Link is secure

Let customers know that Link is secure and uses 256-bit encryption; a lock icon can also be used to help convey that Link uses encryption. Explain that your app does not have access to their credentials. If your app implements the best practice of allowing users to disconnect accounts from within the app, explaining that they can choose to unlink their account later can increase users' confidence in their control over their data.

Provide a polished, engaging flow

A Link hosting flow that is engaging, polished, and reflects your brand conveys the legitimacy and importance of linking an account. Illustrations and interactive elements can all be a part of your pre-Link messaging.

Use multiple channels to engage users

If a user does not link an account during their first interaction with your app, you can use other channels such as email, text, or mobile notifications to remind them. These channels should use the same best practices as your in-app UI. You can also use these channels to notify users when they need to take action to repair a linked account via update mode.

Pre-Link messaging examples

Below are some examples of fictional Plaid-powered apps that incorporate elements of best-practice messaging. While every app will have its own unique pre-Link UI, these examples are intended to provide inspiration and demonstrate how the principles above can be applied.

Payments example
Screenshot of a pre-Link pane incorporating pre-Link best practices

This pre-Link flow conveys the benefit to the user, presents Link as the default experience, and uses social proof to show that Link is a secure solution trusted by many users. It mentions Plaid by name before launching the Link flow, helping the user understand that Plaid is trusted by the app. It also clearly explains what customer-permissioned data the app will be using, how that data will be used, and that the user can revoke access to that data.

Lending example
Screenshot of a pre-Link pane incorporating pre-Link best practices

This pre-Link pane conveys the benefit to the user of linking an app, presents Link as the default experience, explains that Link is secure, and uses a polished design with a cute illustration.

Personal financial management example
Screenshot of a pre-Link pane incorporating pre-Link best practices

This pre-Link pane conveys the benefit to the user, explains that Link is secure, and contains a link to additional security messaging with more detail on security practices, including an explanation of how the user can manage their linked account.

Email messaging example
Screenshot of an email ecouraging the user to link an account

This followup email, sent when a user does not link an account within 24 hours of signing up for the app, uses the same branding as the main app, contains a clear call to action, and explains the benefits of Link and why the user should link their account.

Post-Link messaging best practices

While post-Link messaging has a less direct impact on conversion, it can still impact the confidence your users have in Plaid and in your app.

Present a success screen

Let the user know that they successfully linked their account to your app. You can also show some of the data that your app has collected, so that the user can have proof that the link process worked correctly. If applicable, have a CTA on this screen that allows them to link another account.

Allow users to manage linked Items

Having an area within your app where users can view, manage, or remove linked Items is a privacy and security best practice. It can also minimize the risk of duplicate Items (when a user accidentally adds the same Item twice) and help users fix Items that are unhealthy and need to go through update mode.

Post-Link messaging example

Screenshot of a post-Link pane incorporating post-Link best practices

This post-Link pane includes a success screen to instill confidence. It incorporates the account mask, which lets the user know their account data was retrieved, and incorporates a call to action to link another account.

Next steps

To measure the impact of these steps or set up an experiment to evaluate them, see Measuring Link conversion. For more conversion maximization tips, see Maximizing Link conversion.

link react native react native v5 v7 migration

5.x to 7.x/8.x Migration Guide

Reference for migrating the Link React Native SDK from 5.x to 7.x or 8.x

Overview

This article provides a guide on how to upgrade a Plaid integration from the React Native 5.x SDK to the 7.x or 8.x SDK.

Update Android versions

In your build.gradle, you no longer need to specify the sdk-core or okhttp3 dependencies.

  • Remove implementation 'com.plaid.link:sdk-core:3.2.0+'
  • Remove implementation 'com.squareup.okhttp3:okhttp:4.9.0+'

Update iOS versions

  1. Update your minimum deployment target to 11 or greater:

    1platform :ios, '11.0'

  2. Update your Plaid pod dependency to 2.2.2 or greater:

    1pod 'Plaid', '~> 2.2.2'

Update Plaid component

The Plaid Link SDK now supports TypeScript! PlaidLink renders a Pressable component, which wraps the component you provide and intercepts onPress events to open Link. Additionally, the structure of the inputs has changed.

  • Pass in all properties using the tokenConfig
  • You must not use the oauthNonce or oauthRedirectUri

You can use the children prop to pass in the component that will be wrapped by PlaidLink. linkLogLevel has been added as an optional parameter, which can be used to output useful debugging information.

Public key integrations

Note that tokenConfig implementations are preferred to the deprecated publicKeyConfig implementation. You can migrate to a token configuration using the Link Token migration guide.

If you are using the deprecated public key integration, please be aware of these changes:

  • Pass in all properties using publicKeyConfig:
    • product has been renamed to products
    • env has been renamed to environment
    • The oauthStateId prop has been removed and is no longer needed
    • oauthNonce and oauthRedirectUri are now encapsulated in oauthConfiguration
    • component and componentProps have been removed and you may now use children to pass in a component
    • The payment_token prop has been removed, so all tokens should be passed through the token
    • Some fields are now required: products, language, countryCodes, and environment

Update Success, Exit and Event types

The output types for Success, Exit and Event have been unified across Android and iOS. For a full listing of changes, see the platform-specific migration guides:

Output type changes for Android

Output type changes for iOS

For the full API specifications, see the main docs.

(Optional) Use the usePlaidEmitter hook

In order to get onEvent callbacks you may now use the usePlaidEmitter hook.

1usePlaidEmitter((event) => {
2  console.log(event);
3});

errors rate limit exceeded

Rate Limit Exceeded Errors

Guide to troubleshooting rate limit exceeded errors

Rate limit table

Errors of type RATE_LIMIT_EXCEEDED will occur when the rate limit for a particular endpoint has been exceeded. Default rate limit thresholds for some of the most commonly rate-limited endpoints are shown below. Note that these tables are not an exhaustive listing of all Plaid rate limits or rate-limited endpoints, that some users may experience different rate limit thresholds from those shown, and that rate limits are subject to change at any time.

In general, Plaid default rate limits are set such that using the API as designed should typically not cause a rate limit to be encountered. If your use case requires a higher rate limit, contact your Account Manager or file a Support request.

Production and Development rate limits
EndpointMax requests per ItemMax requests per client
/accounts/balance/get5 per minute1,200 per minute
/accounts/get15 per minute15,000 per minute
/asset_report/createN/A30 per minute
/asset_report/get15 per minute1,000 per minute
/asset_report/refreshN/A30 per minute
/auth/get15 per minute12,000 per minute
/identity/get15 per minute2,000 per minute
/identity_verification/*N/A2,000 per minute
/institutions/getN/A25 per minute
/institutions/get_by_idN/A400 per minute
/investments/holdings/get15 per minute2,000 per minute
/investments/transactions/get30 per minute20,000 per minute
/item/get15 per minute5,000 per minute
/item/remove30 per minute2,000 per minute
/liabilities/get15 per minute1,000 per minute
/processor/token/createN/A500 per minute
/signal/evaluate70 per hour, 10 per transaction per hour50 per second
/signal/decision/reportN/A4,000 per minute
/signal/prepareN/A2,000 per minute
/signal/return/reportN/A4,000 per minute
/transactions/enrichN/A100 per minute
/transactions/get30 per minute20,000 per minute
/transactions/recurring/get20 per minute1,000 per minute
/transactions/refresh2 per minute100 per minute
/transactions/sync50 per minute2,500 per minute
/transfer/authorization/createN/A5,000 per minute
/transfer/cancelN/A250 per minute
/transfer/createN/A5,000 per minute
/transfer/event/syncN/A5,000 per minute
/transfer/intent/createN/A5,000 per minute
/transfer/migrate_accountN/A250 per minute
/transfer/recurring/cancelN/A250 per minute
/transfer/recurring/createN/A5,000 per minute
/transfer/refund/cancelN/A250 per minute
/transfer/refund/createN/A5,000 per minute
/transfer/*/getN/A5,000 per minute
/transfer/*/listN/A100 per minute
/watchlist_screening/*N/A2,000 per minute
Sandbox rate limits
EndpointMax requests per ItemMax requests per client
/accounts/balance/get25 per minute100 per minute
/accounts/get100 per minute5,000 per minute
/asset_report/createN/A30 per minute
/asset_report/get1,000 per minute1,000 per minute
/asset_report/refreshN/A100 per minute
/auth/get100 per minute500 per minute
/identity/get100 per minute1,000 per minute
/identity_verification/*N/A500 per minute
/institutions/getN/A10 per minute
/institutions/get_by_idN/A400 per minute
/investments/holdings/get100 per minute1,000 per minute
/investments/transactions/get100 per minute1,000 per minute
/item/get40 per minute5,000 per minute
/item/remove100 per minute500 per minute
/liabilities/get10 per minute1,000 per minute
/processor/token/createN/A500 per minute
/signal/evaluate70 per hour, 10 per transaction per hour30 per second
/signal/decision/reportN/A4,000 per minute
/signal/prepareN/A2,000 per minute
/signal/return/reportN/A4,000 per minute
/transactions/enrichN/A100 per minute
/transactions/get80 per minute1,000 per minute
/transactions/recurring/get20 per minute1,000 per minute
/transactions/refresh2 per minute100 per minute
/transactions/sync50 per minute1,000 per minute
/transfer/authorization/createN/A100 per minute
/transfer/createN/A100 per minute
/transfer/intent/createN/A100 per minute
/transfer/recurring/createN/A100 per minute
/transfer/refund/createN/A100 per minute
/watchlist_screening/*N/A500 per minute

ACCOUNTS_LIMIT

Too many requests were made to the /accounts/get endpoint.
Common causes
  • Too many requests were made in a short period of time. Requests to /accounts/get in Production and Development environments are rate limited at a maximum of 15 requests per Item per minute and 15,000 per client per minute. In the Sandbox, they are limited at a maximum of 100 per Item per minute and 5,000 per client per minute.
Troubleshooting steps
1http code 429
2{
3 "error_type": "RATE_LIMIT_EXCEEDED",
4 "error_code": "ACCOUNTS_LIMIT",
5 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

ACCOUNTS_BALANCE_GET_LIMIT

Too many requests were made to the /accounts/balance/get endpoint.
Common causes
  • Too many requests were made in a short period of time by a single client. Requests to /account/balance/get in Production and Development environments are client rate limited to 1,200 requests per client per minute. In the Sandbox environment, they are client rate limited at a maximum of 100 requests per client per minute.
Troubleshooting steps
1http code 429
2{
3 "error_type": "RATE_LIMIT_EXCEEDED",
4 "error_code": "ACCOUNTS_BALANCE_GET_LIMIT",
5 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

ADDITION_LIMIT

You have exceeded your addition limit in our Development environment. To increase it, or raise it from zero, contact us.
Sample user-facing error message
Addition Limit Exceeded: The client_id associated with this account has exceeded the maximum number of additions allowed in development mode. Contact Support to resolve
Common causes
  • You attempted to add more Items than currently allowed in the Development environment. The default number of Items allowed in the Development environment can be either 0 or 5, and requesting Development access can increase this number to 100.
  • Note that active Items are counted differently in Development than in Production. Unlike in Production, an Item in Development is counted toward the Item limit as soon as the end user successfully submits valid credentials, even if they do not end up completing the link process, and remains counted even if the access_token is removed.
Troubleshooting steps
1http code 429
2{
3 "error_type": "RATE_LIMIT_EXCEEDED",
4 "error_code": "ADDITION_LIMIT",
5 "error_message": "development addition attempt limit exceeded for this client_id. contact support to increase the limit.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

AUTH_LIMIT

Too many requests were made to the /auth/get endpoint.
Common causes
  • Too many requests were made in a short period of time. Requests to /auth/get in Production and Development environments are rate limited at a maximum of 15 requests per Item per minute and 12,000 per client per minute. In the Sandbox, they are rate limited at a maximum of 100 requests per Item per minute and 500 requests per client per minute.
Troubleshooting steps
1http code 429
2{
3 "error_type": "RATE_LIMIT_EXCEEDED",
4 "error_code": "AUTH_LIMIT",
5 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

BALANCE_LIMIT

Too many requests were made to the /accounts/balance/get endpoint.
Common causes
  • Too many requests were made for a single Item in a short period of time. Requests to /account/balance/get in Production and Development environments are Item rate limited at a maximum of 5 requests per Item per minute. In the Sandbox environment, they are Item rate limited at a maximum of 25 requests per Item per minute.
Troubleshooting steps
1http code 429
2{
3 "error_type": "RATE_LIMIT_EXCEEDED",
4 "error_code": "BALANCE_LIMIT",
5 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

IDENTITY_LIMIT

Too many requests were made to the /identity/get endpoint.
Common causes
  • Too many requests were made in a short period of time. Requests to /identity/get in Production and Development environments are rate limited at a maximum of 15 requests per Item per minute and 2,000 per client per minute. In the Sandbox environment, they are rate limited at a maximum of 100 requests per Item per minute and 1,000 requests per client per minute.
Troubleshooting steps
1http code 429
2{
3 "error_type": "RATE_LIMIT_EXCEEDED",
4 "error_code": "IDENTITY_LIMIT",
5 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INSTITUTIONS_GET_LIMIT

Too many requests were made to the /institutions/get endpoint.
Common causes
  • Too many requests were made in a short period of time. Requests to /institutions/get in Production and Development environments are rate limited at a maximum of 25 per client per minute. In the Sandbox environment, they are rate limited at a maximum of 10 requests per client per minute.
Troubleshooting steps
1http code 429
2{
3 "error_type": "RATE_LIMIT_EXCEEDED",
4 "error_code": "INSTITUTIONS_GET_LIMIT",
5 "error_message": "rate limit exceeded for attempts to access \"institutions get by id\". please try again later",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INSTITUTIONS_GET_BY_ID_LIMIT

Too many requests were made to the /institutions/get_by_id endpoint.
Common causes
  • Too many requests were made in a short period of time. Requests to /institutions/get_by_id are rate limited at a maximum of 400 requests per client per minute.
Troubleshooting steps
1http code 429
2{
3 "error_type": "RATE_LIMIT_EXCEEDED",
4 "error_code": "INSTITUTIONS_GET_BY_ID_LIMIT",
5 "error_message": "rate limit exceeded for attempts to access \"institutions get by id\". please try again later",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVESTMENT_HOLDINGS_GET_LIMIT

Too many requests were made to the /investments/holdings/get endpoint.
Common causes
  • Too many requests were made in a short period of time. Requests to /investments/holdings/get in Production and Development environments are rate limited at a maximum of 15 requests per Item per minute and 2,000 per client per minute. In the Sandbox environment, they are rate limited at a maximum of 100 requests per Item per minute and 1,000 requests per client per minute.
Troubleshooting steps
1http code 429
2{
3 "error_type": "RATE_LIMIT_EXCEEDED",
4 "error_code": "INVESTMENT_HOLDINGS_GET_LIMIT",
5 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVESTMENT_TRANSACTIONS_LIMIT

Too many requests were made to the /investments/transactions/get endpoint.
Common causes
  • Too many requests were made in a short period of time. Requests to /investments/transactions/get in Production and Development environments are rate limited at a maximum of 30 requests per Item per minute and 20,000 per client per minute. In the Sandbox environment, they are rate limited at a maximum of 100 requests per Item per minute and 1,000 requests per client per minute.
Troubleshooting steps
1http code 429
2{
3 "error_type": "RATE_LIMIT_EXCEEDED",
4 "error_code": "INVESTMENT_TRANSACTIONS_LIMIT",
5 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

ITEM_GET_LIMIT

Too many requests were made to the /item/get endpoint.
Common causes
  • Too many requests were made in a short period of time. Requests to /item/get in Production and Development environments are rate limited at a maximum of 15 requests per Item per minute and 5,000 per client per minute. In the Sandbox environment, they are rate limited at a maximum of 40 requests per Item per minute and 5,000 requests per client per minute.
Troubleshooting steps
1http code 429
2{
3 "error_type": "RATE_LIMIT_EXCEEDED",
4 "error_code": "ITEM_GET_LIMIT",
5 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

RATE_LIMIT

Too many requests were made.
Common causes
  • Too many requests were made in a short period of time.
  • Sandbox credentials (the username user_good or user_custom) were used to attempt to log in to Production or Development. Because using these credentials in a live environment is a common misconfiguration, they are frequently subject to rate limiting in those environments.
  • A Link attempt was detected as potential attempted abuse. For example, this may occur if a user enters their credentials incorrectly too many times in a row.
Troubleshooting steps
1http code 429
2{
3 "error_type": "RATE_LIMIT_EXCEEDED",
4 "error_code": "RATE_LIMIT",
5 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

TRANSACTIONS_LIMIT

Too many requests were made to the /transactions/get endpoint.
Common causes
  • Too many requests were made in a short period of time. Requests to /transactions/get in Production and Development environments are rate limited at a maximum of 30 requests per Item per minute and 20,000 per client per minute. In the Sandbox environment, they are rate limited at a maximum of 80 requests per Item per minute and 1,000 requests per client per minute.
Troubleshooting steps
1http code 429
2{
3 "error_type": "RATE_LIMIT_EXCEEDED",
4 "error_code": "TRANSACTIONS_LIMIT",
5 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

TRANSACTIONS_SYNC_LIMIT

Too many requests were made to the /transactions/sync endpoint.
Common causes
  • Too many requests were made in a short period of time. Requests to /transactions/sync in Production and Development environments are rate limited at a maximum of 50 requests per Item per minute and 2,500 per client per minute. In the Sandbox environment, they are rate limited at a maximum of 50 requests per Item per minute and 1,000 requests per client per minute.
Troubleshooting steps
1http code 429
2{
3 "error_type": "RATE_LIMIT_EXCEEDED",
4 "error_code": "TRANSACTIONS_SYNC_LIMIT",
5 "error_message": "rate limit exceeded for attempts to access this item. please try again later",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

errors link

Link web

Guide to troubleshooting Link errors on the web

Most errors returned by Link are an SDK-specific representation of an API error. For troubleshooting help, see the guidance for the specific API error.

In addition, there is one Link-specific error that does not correspond to an API error:

institution-poor-health-error

The user is trying to link to an institution with poor Plaid connectivity health.
Sample user-facing error message
We're currently experiencing connectivity issues with this bank: You can try again later or find another bank to continue
Link user experience

Your user will see a warning pane before they enter their credentials, telling them that adding the account may fail and suggesting that they link a different account.

Common causes
  • The institution is experiencing a temporary disruption of connectivity to Plaid.
Troubleshooting steps

If the problem persists, file a Plaid support ticket.

1http code 400
2{
3 "error_type": "",
4 "error_code": "institution-poor-health-error",
5 "error_message": null,
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

oauth-error

Returned when the OAuth login session for a user either times out or errors out
Sample user-facing error message
An error has occurred linking your account:
Link user experience

Your user will be shown an error message indicating that their account was not successfully linked and will be prompted to retry their login attempt.

Common causes
  • Your user did not complete their OAuth login attempt within 10 minutes.
  • Plaid is experiencing internal system issues.
Troubleshooting steps
1http code 400
2{
3 "error_type": "",
4 "error_code": "oauth-error",
5 "error_message": null,
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

link modular link guide

Modular Link (UK/EU)

Guide to implementing customised Link flows

Introduction

For UK/EU OAuth flows, Plaid offers Modular Link: a fully customisable end-to-end flow that maintains the best-in-class developer experience of Link. With Modular Link, you can create your own:

  • Institution selection pane
  • Loading states
  • Confirmation/Error panes

Modular Link is not enabled by default in any Plaid environment, even if you are already enabled for Payment Initiation. To request that your account be enabled for Modular Link, contact your Plaid Account Manager.

Link token creation

For Modular Link flows, Link tokens must be initialised with an institution_id and eu_config object. Calling the /institutions/get endpoint will return a list of objects representing institutions supported by Plaid. In this case, you'll want to set both options.oauth and options.include_optional_metadata to true. Each institution in the response will include a name, logo, and institution_id. You can use the name and logo to create an institution selection pane. After the user selects an institution, pass the corresponding institution_id into the /link/token/create call.

For the eu_config object, the headless boolean is by default set to false. When it’s set to true, Link will not display any visual UI but will still handle redirects and communication with the bank in the background.

Select Language
1// Using Express
2const express = require('express');
3const app = express();
4app.use(express.json());
5
6const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
7
8const configuration = new Configuration({
9  basePath: PlaidEnvironments[process.env.PLAID_ENV],
10  baseOptions: {
11    headers: {
12      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
13      'PLAID-SECRET': process.env.PLAID_SECRET,
14      'Plaid-Version': '2020-09-14',
15    },
16  },
17});
18
19const client = new PlaidApi(configuration);
20
21app.post('/api/create_link_token', async function (request, response) {
22  const configs = {
23    user: {
24      // This should correspond to a unique id for the current user.
25      client_user_id: 'user-id',
26    },
27    client_name: 'Plaid Test App',
28    products: [Products.PaymentInitiation],
29    language: 'en',
30    webhook: 'https://webhook.sample.com',
31    country_codes: [CountryCode.Gb],
32    payment_initiation: {
33      payment_id: paymentID,
34    },
35    eu_config: {
36      headless: true,
37    },
38    institution_id: "USER_SELECTED_INSTITUTION_ID",
39  };
40  try {
41    const createTokenResponse = await client.linkTokenCreate(configs);
42    response.json(createTokenResponse.data);
43  } catch (error) {
44    // handle error
45  }
46});

Mobile SDK initialisation

For Android and iOS flows, follow the instructions in the Android and iOS guides. The only change is in the LinkTokenConfiguration, where you will set noLoadingState to true. When this field is set, Plaid will not show any of its own loading states.

Android configuration
Select Language
1val linkTokenConfiguration = linkTokenConfiguration {
2  token = "LINK_TOKEN_FROM_SERVER"
3  noLoadingState = true
4}
iOS configuration
Select Language
1var linkConfiguration = LinkTokenConfiguration(
2    token: "<#LINK_TOKEN_FROM_SERVER#>",
3    onSuccess: { linkSuccess in
4        // Send the linkSuccess.publicToken to your app server.
5    }
6)
7
8linkConfiguration.noLoadingState = true

Custom loading states

Once Plaid is initialised, you can begin displaying your loading animation. Link will handle the redirect to the bank and you can leave the loading state running in the background. After the user is done authenticating, Plaid will redirect back to your application where the loading state is still running.

Confirmation and error panes

Plaid uses callbacks to indicate success or error states that enable you to present your custom screens. onSuccess will be called for successful payments and onExit will be called for flows ending in errors.

link handle invalid link token

Handling an invalid Link Token

Catch the error in the onExit callback and refetch a new link_token for the next time the user opens Link

Occasionally, the end user may invalidate the existing link_token that was used to open Link by taking too long to go through the flow (30+ minutes), or attempting too many invalid logins. If this happens, Link will exit with an INVALID_LINK_TOKEN error code.

To allow your user to open Link again, recognize the error in the onExit callback, fetch a new link_token, and use it to reinitialize Link. You can obtain a new link_token by making another /link/token/create request:

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});

For the Link web integration, reinitializing Link means creating a new iframe. To avoid stacking iframes for each Link initialization, you can clean up the old iframe by calling the destroy() method on the Plaid Link handler.

1// Initialize Link with a new link_token each time.
2const configs = {
3  token: (await $.post('/create_link_token')).link_token,
4  onSuccess: (public_token, metadata) => {
5    // Send the public_token to your app server.
6  },
7  onExit: (err, metadata) => {
8    // The user exited the Link flow with an INVALID_LINK_TOKEN error.
9    // This can happen if the token expires or the user has attempted
10    // too many invalid logins.
11    if (err != null && err.error_code === 'INVALID_LINK_TOKEN') {
12      linkHandler.destroy();
13      linkHandler = Plaid.create({
14        ...configs,
15        // Fetch a new link_token because the old one was invalidated.
16        token: (await $.post('/create_link_token')).link_token,
17      });
18    }
19    // metadata contains the most recent API request ID and the
20    // Link session ID. Storing this information is helpful
21    // for support.
22  },
23};
24
25let linkHandler = Plaid.create(configs);

When the user is ready, they will be able to reopen Link and go through the authentication process again.

launch checklist

Launch in Production checklist

Check off these recommended steps before launching your app in Production

Below is a list of recommended steps to take before launching your Plaid integration in production. While they might not all be required for the minimal operation of your application, the steps below will help to make your Plaid integration more robust, secure, efficient, and maintainable.

For a similar list of steps in an easy-to-follow, PDF guide format, see the Plaid implementation handbook.

Production setup

You must migrate to Production to use more than 100 live (non-Sandbox) Items. Note that Items created on the Sandbox or Development environments cannot be migrated to Production.

Link setup

Follow the steps below to assist users in completing the Link flow, help ensure compliance with Plaid's policies, and avoid being billed for unneeded products.

You may find it helpful to know that some of our customers link to Plaid's privacy policy within their own privacy policy, while others surface a separate just-in-time notice and consent page during their onboarding flow. Ultimately, it is up to you to determine how to obtain any legally required consents.

Callbacks

Handle callbacks beyond just onSuccess in order to gracefully handle errors and build analytics around Link.

Webhook configuration

Plaid uses webhooks for many common flows. If your integration does any of the following, webhooks are required or strongly recommended:

  • (Any product) Your application is calling a Plaid endpoint for an Item repeatedly, over a period of time, not just immediately after Link.
  • (Transactions or Investments) You are accessing transactions made after the end user linked their Item.
  • (Auth) You are using automated micro-deposits for account verification.
  • (Assets) You are creating Asset Reports.
  • (Income) You are verifying a user's income.
  • (Payment Initiation (UK and Europe)) You are initiating payments.
  • (Virtual Accounts (UK and Europe) or Transfer) You are sending or receiving funds.

Error handling

Link in update mode

Update mode is used to fix Items that have entered an error state (for example, because a user changed their password). If your application needs to access an Item repeatedly over a period of time, rather than just immediately after Link, implementing update mode logic is strongly recommended.

Storage & logging

Log Plaid identifiers and IDs properly to enhance security, when contacting Support about a specific request or callback, and for finding specific entries in the Activity Log. For more information, see Dashboard logs and troubleshooting.

Ensure that the following identifiers are securely logged, as they will be needed when contacting Support about a specific request or callback.

Item management

Multi-app use cases

Product-specific recommendations

Auth

If you are using Auth for an account funding use case, see the Plaid account funding guide for use case specific recommendations.

Balance

If you are using Balance for an account funding use case, see the Plaid account funding guide for use case specific recommendations.

Identity

If you are using Identity for an account funding use case, see the Plaid account funding guide for use case specific recommendations.

Transactions

Investments

Assets

Payment Initiation

Virtual Accounts

Income

See the Plaid income verification solution guide for use case specific recommendations.

Identity Verification

See the Plaid Identity Verification and Monitor solution guide for use case specific recommendations.

Monitor

See the Plaid Identity Verification and Monitor solution guide for use case specific recommendations.

transactions

Introduction to Transactions

Retrieve up to 24 months of transaction data and stay up-to-date with webhooks.

Link an account
Fetch transactions
Show transactions

Explore API

Overview

Transactions data can be useful for many different applications, including personal finance management, expense reporting, cash flow modeling, risk analysis, and more. Plaid's Transactions product allows you to access a user's transaction history for depository type accounts such as checking and savings accounts, credit type accounts such as credit cards, and student loan accounts. For transaction history from investment accounts, use Plaid's Investments product.

Transactions data available via /transactions/sync includes transaction date, amount, category, merchant, location, and more. Transaction data is lightly cleaned to populate the name field, and more thoroughly processed to populate the merchant_name field.


1{
2      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
3      "amount": 2307.21,
4      "iso_currency_code": "USD",
5      "unofficial_currency_code": null,
6      "category": [
7        "Shops",
8        "Computers and Electronics"
9      ],
10      "category_id": "19013000",
11      "check_number": null,
12      "date": "2023-01-29",
13      "datetime": "2023-01-27T11:00:00Z",
14      "authorized_date": "2023-01-27",
15      "authorized_datetime": "2023-01-27T10:34:50Z",
16      "location": {
17        "address": "300 Post St",
18        "city": "San Francisco",
19        "region": "CA",
20        "postal_code": "94108",
21        "country": "US",
22        "lat": 40.740352,
23        "lon": -74.001761,
24        "store_number": "1235"
25      },
26      "name": "Apple Store",
27      "merchant_name": "Apple",
28      "payment_meta": {
29        "by_order_of": null,
30        "payee": null,
31        "payer": null,
32        "payment_method": null,
33        "payment_processor": null,
34        "ppd_id": null,
35        "reason": null,
36        "reference_number": null
37      },
38      "payment_channel": "in store",
39      "pending": false,
40      "pending_transaction_id": null,
41      "personal_finance_category": {
42        "primary": "GENERAL_MERCHANDISE",
43        "detailed": "GENERAL_MERCHANDISE_ELECTRONICS"
44      },
45      "account_owner": null,
46      "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
47      "transaction_code": null,
48      "transaction_type": "place"
49    }

Transactions updates

Transactions data is not static. As time passes, your users will make new transactions, and transactions they made in the past will change as they are processed by the financial institution. To learn more about how transactions are processed and can change, see Transaction states.

Plaid checks for updated transactions data multiple times per day and uses webhooks to notify you of any changes so you can keep your app up to date. For more detail on how to listen and respond to transaction update webhooks, see Transaction webhooks.

The frequency of transactions update checks will depend on the institution. To learn when an Item was last checked for updates, you can view the Item in the Item Debugger. If you would like to display this information in your app's UI to help users understand the freshness of their data, it can also be retrieved via API, using the /item/get endpoint.

You can also request an update on-demand via the /transactions/refresh endpoint, which is available as an add-on for Transactions customers. To request access to this endpoint, submit a product access request or contact your Plaid account manager.

Recurring transactions

If your app involves personal financial management functionality, you may want to view a summary of a user's inflows and outflows. The /transactions/recurring/get endpoint provides a summary of the recurring outflow and inflow streams and includes insights about each recurring stream including the category, merchant, last amount, and more. /transactions/recurring/get is available as an add-on for Transactions customers in the US, Canada, and UK. To request access to this endpoint, submit a product access request or contact your Plaid account manager.

Sample app demo and code

Try out the Pattern Demo for a demonstration of a sample app that uses Plaid's Transactions product for the personal financial management use case to calculate and display a customer's net worth and spending habits and allows them to link multiple financial institutions.

For a more robust example of an app that incorporates transactions, along with sample code for transactions reconciliation, see the Node-based Plaid Pattern sample app.

Updating your app

If you've already built an app using Plaid's /transactions/get endpoint, see the Transactions Sync migration guide to learn about Plaid's latest Transactions API and how to simplify your integration by migrating to /transactions/sync.

Next steps

To get started building with Transactions, see Add Transactions to your App.

If you're ready to launch to Production, see the Launch checklist.

link link token migration guide

Link token migration guide

How to migrate your application from the public key to a Link token

Introduction

Plaid has introduced a new link_token, which replaces the static public_key. This is an improvement that provides better error validation, more advanced security, and enables Link event logs to be surfaced in the Plaid Dashboard. While Plaid does not plan to discontinue support for existing public_key integrations, it is recommended that you upgrade your integration to use a link_token, as it enables enhanced capabilities, and future Plaid development and features will be based on the link_token infrastructure. Link tokens are also required for new OAuth integrations.

If you are unable to migrate to Link tokens at this time, see maintaining a public key integration for instructions on working with legacy public keys.

This guide covers the client and server-side changes required to implement the new link_token. Here's an overview of the updates before we dive into the details.

The Plaid flow begins when your user wants to connect their bank account to your app.
Step diagram
1Call /link/token/create to create a link_token and pass the temporary token to your app's client.
Step 1 diagram
2Use the link_token to open Link for your user. In the onSuccess callback, Link will provide a temporary public_token.
Step 2 diagram
3Call /item/public_token/exchange to exchange the public_token for a permanent access_token and item_id for the new Item.
Step 3 diagram
4Store the access_token and use it to make product requests for your user's Item.
Step 4 diagram

What's new

  • Link will now be initialized with a new link_token. The link_token replaces all previous methods of initializing Link, including the public_key (for initial Link), the public_token (for update mode), and the payment_token (for Payment Initiation).
  • The new endpoint to create the link_token is /link/token/create.
  • The INVALID_LINK_TOKEN error code is now available to gracefully handle invalidated tokens.
  • Link events from sessions created with the new link_token will be surfaced in the Logs section of the Dashboard. However, Link events from sessions created with the public_key will not.

Link tokens

The link_token is a new type of token that is created by your app's server and passed to your app's client to initialize Link. The Link configuration parameters that were previously set within Link itself are now set via parameters passed to /link/token/create and conveyed to Link via the link_token. If these configurations are still set client-side when using the link_token, they will not have any effect on Link behavior.

Update your integration

The overall process for updating your integration is:

  1. Update your server to create a link_token.
  2. Update your client to pass the link_token and handle INVALID_LINK_TOKEN errors.
  3. Ensure you have updated all Link entry points, including those for update mode.
  4. Test your integration.
  5. Update any callsites that use the public_key for authentication to use the client_id and secret instead, then re-test those callsites.
  6. Disable the public_key.

Detailed instructions for each step can be found below.

Update your server

Add a new authenticated endpoint to your app's server to create a link_token by calling /link/token/create.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['transactions'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});

Many of the parameters to /link/token/create are the same as parameters previously set in Link. Aside from the change to snake_case from camelCase, there are a few substantive differences, summarized below. Note that these bullets are only a summary; for the full /link/token/create endpoint definition, see the API Reference.

  • A new required parameter, user.id, has been added. This should be a unique identifier, such as the user ID of the end user in your application. It should not contain personally identifiable information, such as a phone number or email address.
  • language and country_codes, which were previously optional, are now required.
  • accountSubtypes has been replaced by the account_filters parameter, and its syntax has changed.

In addition, there are a few differences relevant specifically to European integrations:

  • The oauthNonce parameter is no longer used, since it is effectively replaced by user.id.
  • For the Payment Initiation product, The paymentToken is no longer used, and /payment_initiation/payment/token/create has been deprecated. Instead, the payment_id should be provided to /link/token/create via the payment_initiation.payment_id parameter. Initializing Link with the returned link_token will launch the Payment Initiation flow.
Authenticate your app

The endpoint used to create a link_token should only be available to users that are logged in to your app. Once your user is logged in, pass an identifier that uniquely identifies your user into the user.client_user_id field. The value of this field should not be personally identifiable information such as an email address or phone number. Using user.client_user_id will allow for easier debugging in the Dashboard logs. You will be able to search for Link logs that belong to one of your end users.

As this update involves an additional API call when adding an Item, create a link_token when your user initially visits your app to avoid adding latency to your Link flow.

Update your client

For each of your web and mobile apps, use the new endpoint you created to fetch a link_token, then pass it into one of Plaid's Link SDKs to initialize Link. You can then safely remove the public_key and other client-side configs that are now configured in the /link/token/create request.

If the token expires or the user enters too many invalid credentials, the link_token can become invalidated. If it does get into an invalid state, Link will exit with an INVALID_LINK_TOKEN error code. By recognizing when this error occurs in the onExit callback, you can generate a fresh link_token for the next time your user opens Link.

Update Link web

The code below demonstrates code that passes the new link_token to Link. For more in-depth coverage on how to integrate with Link web, see the Link web docs.

Note that in the error handling section, in order to handle an invalid link_token for Link in the browser, you will need to gracefully clean up the old iframe before reinitializing Link. To do this, use the destroy() method and reinitialize Link with a new link_token in the onExit callback.

1<button id="link-button">Link Account</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script type="text/javascript">
4(async function() {
5  const fetchLinkToken = async () => {
6    const response = await fetch('/create_link_token', { method: 'POST' });
7    const responseJSON = await response.json();
8    return responseJSON.link_token;
9  };
10
11  const configs = {
12    // 1. Pass a new link_token to Link.
13    token: await fetchLinkToken(),
14    onSuccess: async function(public_token, metadata) {
15      // 2a. Send the public_token to your app server.
16      // The onSuccess function is called when the user has successfully
17      // authenticated and selected an account to use.
18      await fetch('/exchange_public_token', {
19        method: 'POST',
20        body: JSON.stringify({ public_token: public_token }),
21      });
22    },
23    onExit: async function(err, metadata) {
24      // 2b. Gracefully handle the invalid link token error. A link token
25      // can become invalidated if it expires, has already been used
26      // for a link session, or is associated with too many invalid logins.
27      if (err != null && err.error_code === 'INVALID_LINK_TOKEN') {
28        linkHandler.destroy();
29        linkHandler = Plaid.create({
30          ...configs,
31          token: await fetchLinkToken(),
32        });
33      }
34      if (err != null) {
35        // Handle any other types of errors.
36      }
37      // metadata contains information about the institution that the
38      // user selected and the most recent API request IDs.
39      // Storing this information can be helpful for support.
40    },
41  };
42
43  var linkHandler = Plaid.create(configs);
44
45  document.getElementById('link-button').onclick = function() {
46    linkHandler.open();
47  };
48})();
49</script>
Update Link iOS

The iOS SDK now provides an initWithLinkToken method on both the PLKConfiguration and the PLKPlaidLinkViewController classes that should allow you to easily initialize Link with a link_token.

The code below shows how to initialize Link with the link_token in iOS. For more in-depth coverage on how to integrate with Link iOS, see the iOS docs.

Select Language
1let linkConfiguration = PLKConfiguration(linkToken: "GENERATED_LINK_TOKEN")
2let linkViewDelegate = self
3let linkViewController = PLKPlaidLinkViewController(
4  linkToken: "GENERATED_LINK_TOKEN",
5  configuration: linkConfiguration,
6  delegate: linkViewDelegate,
7)
8if (UI_USER_INTERFACE_IDIOM() == .pad) {
9    linkViewController.modalPresentationStyle = .formSheet;
10}
11present(linkViewController, animated: true)
Update Link Android

The Android SDK exposes a new class called LinkTokenConfiguration. This class accepts the link_token and should be passed into the openPlaidLink method.

The code below demonstrates how to use the LinkTokenConfiguration class to open Link. For more in depth coverage on the Android SDK, see the Android docs.

Select Language
1import android.os.Bundle
2import android.util.Log
3import androidx.appcompat.app.AppCompatActivity
4
5import com.plaid.link.Plaid
6import com.plaid.link.linkTokenConfiguration
7import com.plaid.link.openPlaidLink
8import com.plaid.link.configuration.AccountSubtype
9import com.plaid.link.configuration.LinkLogLevel
10import com.plaid.link.configuration.PlaidEnvironment
11import com.plaid.link.configuration.PlaidProduct
12import com.plaid.link.event.LinkEvent
13import java.util.Locale
14
15class MainActivity : AppCompatActivity() {
16
17  override fun onCreate(savedInstanceState: Bundle?) {
18    super.onCreate(savedInstanceState)
19
20    // Optional
21    Plaid.setLinkEventListener { event -> Log.i("Event", event.toString()) }
22
23    // Open Link – put this inside of a Button / Fab click listener
24    this@MAINACTIVITY.openPlaidLink(
25      linkTokenConfiguration {
26        // required
27        token = "GENERATED_LINK_TOKEN"
28
29        // optional
30        logLevel = LinkLogLevel.WARN // Defaults to ASSERT
31        extraParams = mapOf() // Map of additional configs
32      }
33    );
34  }
35}

Update Link update mode flows

With the introduction of the link_token, /item/public_token/create is deprecated, and Link's update mode is initialized by passing in a link_token rather than a public_token. You can obtain this link_token by calling /link/token/create and providing the user.id of the user whose Item is being updated, along with the access_token for the Item. Make sure to update any update mode flow entry points in addition to updating primary Link flows. For more details and complete sample code, see Updating Items via Link.

1// Initialize Link with the token parameter
2// set to the generated link_token for the Item
3const linkHandler = Plaid.create({
4  token: 'GENERATED_LINK_TOKEN',
5  onSuccess: (public_token, metadata) => {
6    // You do not need to repeat the /item/public_token/exchange
7    // process when a user uses Link in update mode.
8    // The Item's access_token has not changed.
9  },
10  // ...
11});

Test in Sandbox

Once you have updated both your app's client and server, it's time to test that your integration works. The best way to test is by using the test credentials in the Sandbox:

1username: user_good
2password: pass_good

Test your error handling flow for INVALID_LINK_TOKEN by using the Sandbox test credentials to force an error:

1username: user_custom
2password: { "force_error": "INVALID_LINK_TOKEN" }

You can also verify that you have updated correctly by viewing Link event logs in the Plaid Dashboard.

To test your update mode implementation, use the /sandbox/item/reset_login endpoint to force an Item into a state that requires an update, then walk through the test steps above.

Update API endpoints

In order to completely migrate off of the public_key, there are a few Plaid API endpoints that should replace the public_key with the client_id and secret: /institutions/search, /institutions/get_by_id, and /sandbox/public_token/create.

Because the client_id and secret are now used to authenticate the endpoints above, they should only be called from your server. The ability to call them from the client has been removed in the latest client library updates.

Disable the public key

After completing all of the above steps, you can now confidently disable the public_key via the Plaid Dashboard. This can be done on a per-environment basis, with different settings for Sandbox, Development, and Production, to help you test your migration. The public_key can also be disabled separately for Link and for the API. Disabling it for Link means you will be required to use the link_token to initialize Link. Disabling it for the API means that you will be required to use the client_id and secret to call /institutions/search, /institutions/get_by_id, and/sandbox/public_token/create.

It is recommended you disable the public_key as soon as possible to ensure that you do not accidentally add legacy public_key-dependent code to your application.

Conclusion

Congratulations on upgrading to the new link_token! If you require any help migrating to the link_token integration, please contact Plaid Support for assistance.

payment initiation user onboarding and account funding

User onboarding and account funding

Use Plaid to simplify your onboarding and funding flow

In this guide, we first walk through setting up an account linking flow that uses Plaid to connect your user's bank account. We'll then demonstrate how to verify the identity of your users which may help comply with KYC and AML regulations.

Finally, we’ll show how how to initiate payments while requiring that bank accounts involved in money movements are verified.

Before you get started

The Auth, Identity, and Payment Initiation products covered in this guide can immediately be tried out in the Sandbox environment, which uses test data and does not interact with financial institutions.

To gain access to these products in the Development and Production environments, submit a product access Support ticket.

User onboarding

The Plaid flow begins when the user registers with your app. The flow will connect your app to your user's financial institution.
Step diagram
1Your backend creates a link_token by using the/link/token/create endpoint and passes the temporary token to your Client app.
Step 1 diagram
2Your Client app uses the link_token to initiate a Link flow for your user. The onSuccess callback signals that the user has granted your app access to their financial institution.
Step 2 diagram
3The onSuccess payload contains a public_token which, after sending it to your backend, needs to be exchanged for a long-lived access token using the /item/public_token/exchange endpoint.
Step 3 diagram
4Using this access token your backend can now retrieve the user’s bank account numbers via /auth/get or their identity information (such as their full name) via /identity/get.
Step 4 diagram

Adding the Auth and Identity products to your app

The steps listed above are broken down into more detail in the guides linked below. The first guide covers adding the Auth product (e.g. for obtaining the user’s bank account numbers). The second covers the Identity product (e.g. for obtaining the user’s legal name). Both guides describe almost identical steps, so you can follow either one.

The next section will highlight the single difference between the two and will show how you can use both products at the same time.

Creating a Link token

Link token creation is the only step requires changes when requesting both Auth and Identity-related information. To do so, pass both products as part of the /link/token/create request.

1{
2  "client_id": "CLIENT_ID",
3  "secret": "SECRET",
4  "client_name": "Plaid Test App",
5  "user": { "client_user_id": "UNIQUE_USER_ID" },
6  "products": ["auth", "identity"], // using both products
7  "country_codes": ["GB", "NL", "DE"],
8  "language": "en"
9  "webhook": "https://webhook.sample.com",
10}

End user experience

During the Link flow, your user grants permission to all the data products that you request. The images below demonstrate examples of the panes Link will present when requesting access to one or multiple products.

Account funding and withdrawal best practices

This section describes how to use the access_token that was obtained earlier to improve your user's account funding and withdrawal experiences.

Payment Initiation is offered only in Europe. For the US, see Transfer.

Payments in Europe are powered by the Payment Initiation product. See the Add Payment Initiation to your app guide to learn more about setting it up.

The following sections expand on this guide by providing compliance and conversion best practices.

Preselecting a financial institution

By default, Plaid will ask the user to manually select their financial institution. However, there might be cases where you already know which institution your user wants to use. For example, when your user has previously completed a sign up flow, you can increase conversion by skipping this part of the payment flow. This requires two steps:

  1. Call /item/get with the access_token as an input parameter. This endpoint will return the institution_id as part of the response.
  2. Provide the institution_id as part of the payment /link/token/create request.
1{
2  "client_id": "CLIENT_ID",
3  "secret": "SECRET",
4  "client_name": "Plaid Test App",
5  "user": { "client_user_id": "UNIQUE_USER_ID" },
6  "products": ["payment_initiation"],
7  "country_codes": ["GB", "NL", "DE"],
8  "language": "en"
9  "webhook": "https://webhook.sample.com",
10  "payment_initiation": { "payment_id": "PAYMENT_ID" },
11  "institution_id": "INSTITUTION_ID" // preselect institution_id
12}

Compliant account funding

To help comply with KYC & AML regulations you may choose to restrict payments to your app from bank accounts whose owner was previously verified.

Payment Initiation can support this flow by requiring that a payment is to be made from a specific account. The process has three steps:

  1. Call /auth/get with the access_token as an input parameter. This endpoint will return the user’s account numbers as part of the response (Use bacs for the UK and international for the rest of Europe).
  2. Provide one of the account numbers under options as part of the /payment_initiation/payment/create request. See the snippet below as an example.
  3. Provide the institution_id as part of the /link/token/create request, as described in the previous section.

Not all financial institutions support this feature. In the UK there is full support. In the rest of Europe, support may be limited. Plaid will let the user choose any account when their financial institution does not support this feature. It is recommended to also verify the origin of payments as part of your payment reconciliation process.

1{
2  "client_id": "CLIENT_ID",
3  "secret": "SECRET",
4  "recipient_id": "RECIPIENT_ID",
5  "reference": "Sample reference",
6  "amount": {
7    "currency": "GBP",
8    "amount": 1.99
9  },
10  "options": { // additional payee account restriction
11    "bacs": {
12        "account": "26207729",
13        "sort_code": "560029"
14    }
15  }
16}

Compliant withdrawals

To comply with KYC & AML regulations, you may want to restrict outbound money movements to accounts whose owner is verified. You can do this in the following ways:

Using Virtual Accounts

Make sure your virtual account is set up before following these steps. For more information on setting up an account, see Managing virtual accounts.

  1. Follow the Payment Confirmation flow to confirm that funds have settled in your virtual account.
  2. Fetch the payment object by calling /payment_initiation/payment/get with the payment_id of the payment you initiated. The payment object will contain a transaction_id, which corresponds to the payment's underlying virtual account transaction.
  3. Fetch the virtual account transaction by calling /wallet/transaction/get with the transaction_id.
  4. The virtual account transaction will contain account details in the counterparty field.
  5. Execute a Payout using the counterparty details.
Using Auth data
  1. Call /auth/get with the access_token as an input parameter. This endpoint will return the user’s verified account numbers as part of the response (Use bacs for the UK and international for the rest of Europe).
  2. Select accounts that can receive funds by filtering for account.subtype = "checking".
  3. Initiate the withdrawal to any of the filtered accounts. You may want to let the user choose a preferred account in case there are multiple.
Using the request_refund_details flag

This approach is not recommended since it is an optional flag with limited incomplete coverage dependent on the financial institution a payment was initiated to.

  1. Go through the Payment Initiation flow and initiate a payment with the request_refund_details flag enabled.
  2. Fetch the payment object by calling /payment_initiation/payment/get and parse the refund_details field.
  3. Initiate the withdrawal to account specified in the refund_details field.

Next steps

If you're ready to launch to Production, see the Launch checklist.

errors partner

Partner Errors

Guide to troubleshooting partner errors

CUSTOMER_NOT_FOUND

Customer not found
Common causes
  • The end customer could not be found.
Troubleshooting steps
1http code 404
2{
3 "error_type": "PARTNER_ERROR",
4 "error_code": "CUSTOMER_NOT_FOUND",
5 "error_message": "the customer was not found",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

FLOWDOWN_NOT_COMPLETE

Flowdown not complete
Common causes
  • A flowdown, which is a prerequisite for creating an end customer, has not been completed.
Troubleshooting steps
1http code 412
2{
3 "error_type": "PARTNER_ERROR",
4 "error_code": "FLOWDOWN_NOT_COMPLETE",
5 "error_message": "you must complete a flowdown to create and enable customers",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

QUESTIONNAIRE_NOT_COMPLETE

Questionnaire not complete
Common causes
  • A security questionnaire, which is a prerequisite for creating an end customer, has not been submitted.
Troubleshooting steps
1http code 412
2{
3 "error_type": "PARTNER_ERROR",
4 "error_code": "QUESTIONNAIRE_NOT_COMPLETE",
5 "error_message": "you must complete the security questionnaire to create and enable customers",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

CUSTOMER_NOT_READY_FOR_ENABLEMENT

Customer not ready for enablement
Common causes
  • The end customer requires manual approval from Plaid's Partnerships team.
  • The end customer has been denied access to the Plaid API.
Troubleshooting steps
1http code 412
2{
3 "error_type": "PARTNER_ERROR",
4 "error_code": "CUSTOMER_NOT_READY_FOR_ENABLEMENT",
5 "error_message": "this customer is not ready for enablement",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

CUSTOMER_ALREADY_ENABLED

Customer already enabled
Common causes
  • The end customer has already been enabled.
Troubleshooting steps
1http code 400
2{
3 "error_type": "PARTNER_ERROR",
4 "error_code": "CUSTOMER_ALREADY_ENABLED",
5 "error_message": "this customer has already been enabled",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

CUSTOMER_ALREADY_CREATED

Customer already created
Common causes
  • The end customer has already been created.
Troubleshooting steps
1http code 400
2{
3 "error_type": "PARTNER_ERROR",
4 "error_code": "CUSTOMER_ALREADY_CREATED",
5 "error_message": "this customer has already been created",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

LOGO_REQUIRED

Logo required
Common causes
  • A logo is required for this customer because the create_link_customization field was set to true and the co-branded consent field is in use.
Troubleshooting steps
1http code 400
2{
3 "error_type": "PARTNER_ERROR",
4 "error_code": "LOGO_REQUIRED",
5 "error_message": "a logo is required because create_link_customization is set to true and the co-branded consent pane is in use",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_LOGO

Invalid logo
Common causes
  • The logo is not a valid base64-encoded string of a PNG of size 1024x1024.
Troubleshooting steps
1http code 400
2{
3 "error_type": "PARTNER_ERROR",
4 "error_code": "INVALID_LOGO",
5 "error_message": "the logo must be a base64-encoded string of a PNG of size 1024x1024",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

CONTACT_REQUIRED

Contact required
Common causes
  • A billing or technical contact is required, either in the API request or in the Dashboard.
Troubleshooting steps
1http code 400
2{
3 "error_type": "PARTNER_ERROR",
4 "error_code": "CONTACT_REQUIRED",
5 "error_message": "billing or technical contacts must be submitted either in the request or filled in for your team in the dashboard",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

ASSETS_UNDER_MANAGEMENT_REQUIRED

Assets Under Management required
Common causes
  • The assets_under_management field is required because you have a monthly service commitment, but it was omitted from your API request.
Troubleshooting steps
1http code 400
2{
3 "error_type": "PARTNER_ERROR",
4 "error_code": "ASSETS_UNDER_MANAGEMENT_REQUIRED",
5 "error_message": "assets under management must be submitted because your team has a monthly service commitment",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

CUSTOMER_REMOVAL_NOT_ALLOWED

Removal not allowed
Common causes
  • You have attempted to remove an end customer that has already been enabled in the Production environment, which is not allowed.
Troubleshooting steps
1http code 400
2{
3 "error_type": "PARTNER_ERROR",
4 "error_code": "CUSTOMER_REMOVAL_NOT_ALLOWED",
5 "error_message": "removal of a production-enabled end customer is not allowed. talk to your account manager to remove this end customer.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

auth partnerships vesta

Add Vesta to your app

Use Vesta with Plaid Auth to send and receive payments!

Partnership Vesta logo

Overview

Plaid and Vesta have partnered together to enable businesses to transact over ACH with confidence by offering a guarantee for every approved transaction. Plaid’s seamless account-linking experience married with Vesta’s industry-leading fraud detection technology help to both increase conversion and minimize losses. Available as a full-service processing solution or layered on top of your existing payment facilitator, Plaid and Vesta’s Guarantee solution is designed for maximum convenience and flexibility.

With the Plaid + Vesta integration, your users can verify their accounts in seconds by inputting their banking credentials in Plaid’s front-end module. Vesta then runs a fraud risk analysis on the connected account, assesses each transaction and approves it for a guarantee. Once approved, Vesta can either initiate the payment as a full-service solution, or return feedback so you can instruct your existing processor to run the transaction, as a truly processor-agnostic solution.

To get started sign up for Plaid API keys.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Vesta account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Vesta processor_token, which allows you to quickly and securely verify a bank funding source via Vesta's API without having to store any sensitive banking information. Utilizing Plaid + Vesta enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Vesta in order to use the Plaid + Vesta integration. You'll also need to enable your Plaid account for the Vesta integration.

First, you will need to work with the Vesta team to sign up for a Vesta account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Vesta to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Vesta processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Vesta, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Vesta processor_token. You'll send this token to Vesta and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Vesta processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'vesta',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Vesta Production credentials prior to initiating live payment transactions in the Vesta API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

errors assets

Assets Errors

Guide to troubleshooting Assets errors

PRODUCT_NOT_ENABLED

Common causes
  • One or more of the Items in the Asset Report was not initialized with the Assets product. Unlike some products, Assets cannot be initialized "on-the-fly" and must be initialized during the initial link process.
Troubleshooting steps
1http code 400
2{
3 "error_type": "ASSET_REPORT_ERROR",
4 "error_code": "PRODUCT_NOT_ENABLED",
5 "error_message": "",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

DATA_UNAVAILABLE

Common causes
  • One or more of the Items in the Asset Report has experienced an error.
Troubleshooting steps
1http code 400
2{
3 "error_type": "ASSET_REPORT_ERROR",
4 "error_code": "DATA_UNAVAILABLE",
5 "error_message": "unable to pull sufficient data for all items to generate this report. please see the \"causes\" field for more details",
6 "display_message": null,
7 "causes": [
8  {
9   "display_message": null,
10   "error_code": "ITEM_LOGIN_REQUIRED",
11   "error_message": "the login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state",
12   "error_type": "ITEM_ERROR",
13   "item_id": "pZ942ZA0npFEa0BgLCV9DAQv3Zq8ErIZhc81F"
14  }
15 ],
16 "request_id": "HNTDNrA8F1shFEW"
17}
Was this helpful?

PRODUCT_NOT_READY

Note that this error should not be confused with the PRODUCT_NOT_READY error of type ITEM_ERROR, which has different causes.

Common causes
Troubleshooting steps
1http code 400
2{
3 "error_type": "ASSET_REPORT_ERROR",
4 "error_code": "PRODUCT_NOT_READY",
5 "error_message": "",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

ASSET_REPORT_GENERATION_FAILED

Common causes
  • Plaid is experiencing temporary difficulties generating Asset Reports.
Troubleshooting steps

If the error persists, please submit a Support ticket.

1http code 400
2{
3 "error_type": "ASSET_REPORT_ERROR",
4 "error_code": "ASSET_REPORT_GENERATION_FAILED",
5 "error_message": "",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_PARENT

Common causes
  • An endpoint that creates a copy or modified copy of an Asset Report (such as /asset_report/filter or /asset_report/audit_copy/create) was called, but the original Asset Report does not exist, either because it was never successfully created in the first place or because it was deleted.
1http code 400
2{
3 "error_type": "ASSET_REPORT_ERROR",
4 "error_code": "INVALID_PARENT",
5 "error_message": "",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INSIGHTS_NOT_ENABLED

Common causes
1http code 400
2{
3 "error_type": "ASSET_REPORT_ERROR",
4 "error_code": "INSIGHTS_NOT_ENABLED",
5 "error_message": "",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INSIGHTS_PREVIOUSLY_NOT_ENABLED

Common causes
  • /asset_report/get or /asset_report/pdf/get was called with enable_insights set to true by a Plaid developer account that is currently enabled for Asset Reports with Insights, but was not enabled at the time that the report was created.
1http code 400
2{
3 "error_type": "ASSET_REPORT_ERROR",
4 "error_code": "INSIGHTS_PREVIOUSLY_NOT_ENABLED",
5 "error_message": "",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

link measuring conversion

Measuring Link conversion

Learn how to measure Link conversion

Measuring Link conversion

For almost every action your user takes within the Link flow, the onEvent callback will fire, allowing you to track their progress through Link. The most important events are HANDOFF, which indicates that the user has linked an Item, and EXIT, which indicates that the user has exited without linking an account. Your overall conversion rate is measured as the number of HANDOFF events divided by the sum total of HANDOFF and EXIT events. This metric can be used to evaluate A/B tests around conversion or to measure the conversion impact of changes you implement. You can also obtain insight into at what point a user abandoned Link by tracking the metadata.status field within onExit.

1OPEN
2TRANSITION_VIEW
3SELECT_INSTITUTION
4TRANSITION_VIEW
5SUBMIT_CREDENTIALS
6TRANSITION_VIEW
7HANDOFF
1OPEN
2TRANSITION_VIEW
3SELECT_INSTITUTION
4TRANSITION_VIEW
5SUBMIT_CREDENTIALS
6TRANSITION_VIEW
7ERROR
8TRANSITION_VIEW
9SUBMIT_CREDENTIALS
10TRANSITION_VIEW
11ERROR
12TRANSITION_VIEW
13EXIT

As of July 2022, Link no longer issues the SUBMIT_CREDENTIALS event when a user authenticates with an institution that requires OAuth. Link issues the OPEN_OAUTH event when a user chooses to be redirected to the institution’s OAuth portal. It is recommended to track this event instead of SUBMIT_CREDENTIALS.

1OPEN (view_name = CONSENT)
2TRANSITION_VIEW (view_name = SELECT_INSTITUTION)
3SELECT_INSTITUTION
4TRANSITION_VIEW (view_name = OAUTH)
5OPEN_OAUTH
6...
7(The user completes the OAuth flow at their bank)
8...
9TRANSITION_VIEW (view_name = CONNECTED)
10HANDOFF

Though users can go through multiple authentication flow types, you can track user conversion in one funnel by joining the OPEN_OAUTH or SUBMIT_CREDENTIALS events:

1OPEN 
2TRANSITION_VIEW (view_name = SELECT_INSTITUTION) 
3SELECT_INSTITUTION (view_name = OAUTH <or> CREDENTIAL)
4SUBMIT_CREDENTIALS <or> OPEN_OAUTH 
5TRANSITION_VIEW (view_name = CONNECTED)
6HANDOFF

To measure conversion through the OAuth and credentials-based flows separately, filter institutions based on the TRANSITION_VIEW event after the SELECT_INSTITUTION event. 

1...
2SELECT_INSTITUTION
3TRANSITION_VIEW (view_name = OAUTH)
4OPEN_OAUTH
5TRANSITION_VIEW (view_name = CONNECTED)
6HANDOFF
1...
2SELECT_INSTITUTION
3TRANSITION_VIEW (view_name = CREDENTIAL)
4SUBMIT_CREDENTIALS
5TRANSITION_VIEW (view_name = MFA, mfa_type = code)
6SUBMIT_MFA (mfa_type = code)
7TRANSITION_VIEW (view_name = CONNECTED)
8HANDOFF

You can also capture the institution_name field, provided by the onEvent callback, to track which institutions your users are attempting to link.

Analyzing conversion data

Many customers use third-party analytics platforms to analyze conversion data, which can allow you to easily view data by platform or institution. Lower conversion on a specific platform or institution may indicate an implementation problem. For example, lower conversion on mobile for OAuth-supporting institutions may indicate an issue with the handling of OAuth redirects or failure to implement app-to-app.

We recommend tracking conversion data over time to measure the impact of changes to your Link integration.

Next steps

Once you're measuring Link conversion, make sure you're maximizing it. For tips, see Optimizing Link conversion.

api products investments

Investments

API reference for Investments endpoints and webhooks

Endpoints
/investments/holdings/getFetch investment holdings
/investments/transactions/getFetch investment transactions
In this section
HOLDINGS: DEFAULT_UPDATENew holdings available
INVESTMENTS_TRANSACTIONS: DEFAULT_UPDATENew transactions available
INVESTMENTS_TRANSACTIONS: HISTORICAL_UPDATEInvestments data ready

Endpoints

/investments/holdings/get

Get Investment holdings

The /investments/holdings/get endpoint allows developers to receive user-authorized stock position data for investment-type accounts.

investments/holdings/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
options
object
An optional object to filter /investments/holdings/get results. If provided, must not be null.
account_ids
[string]
An array of account_ids to retrieve for the Item. An error will be returned if a provided account_id is not associated with the Item.
Select group for content switcher
Select Language
1// Pull Holdings for an Item
2const request: InvestmentsHoldingsGetRequest = {
3  access_token: accessToken,
4};
5try {
6  const response = await plaidClient.investmentsHoldingsGet(request);
7  const holdings = response.data.holdings;
8  const securities = response.data.securities;
9} catch (error) {
10  // handle error
11}
investments/holdings/get

Response fields and example

accounts
[object]
The accounts associated with the Item
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullablenumber
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullablenumber
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullablenumber
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullablestring
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
holdings
[object]
The holdings belonging to investment accounts associated with the Item. Details of the securities in the holdings are provided in the securities field.
account_id
string
The Plaid account_id associated with the holding.
security_id
string
The Plaid security_id associated with the holding. Security data is not specific to a user's account; any user who held the same security at the same financial institution at the same time would have identical security data. The security_id for the same security will typically be the same across different institutions, but this is not guaranteed. The security_id does not typically change, but may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change.
institution_price
number
The last price given by the institution for this security.

Format: double
institution_price_as_of
nullablestring
The date at which institution_price was current.

Format: date
institution_price_datetime
nullablestring
Date and time at which institution_price was current, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ).
This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00).

Format: date-time
institution_value
number
The value of the holding, as reported by the institution.

Format: double
cost_basis
nullablenumber
The original total value of the holding. This field is calculated by Plaid as the sum of the purchase price of all of the shares in the holding.

Format: double
quantity
number
The total quantity of the asset held, as reported by the financial institution. If the security is an option, quantity will reflect the total number of options (typically the number of contracts multiplied by 100), not the number of contracts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the holding. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the holding. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
securities
[object]
Objects describing the securities held in the accounts associated with the Item.
security_id
string
A unique, Plaid-specific identifier for the security, used to associate securities with holdings. Like all Plaid identifiers, the security_id is case sensitive. The security_id may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change.
isin
nullablestring
12-character ISIN, a globally unique securities identifier. Please note that Plaid's customers must hold a license directly from CUSIP Global Services to receive CUSIP & ISIN data. This field will be null by default for new customers. For existing customers, this field will be null by default starting on Sept 15, 2023. If you would like access to this field, please contact your Plaid Account Manager or reach out to investments-vendors@plaid.com.
cusip
nullablestring
9-character CUSIP, an identifier assigned to North American securities. Please note that Plaid's customers must hold a license directly from CUSIP Global Services to receive CUSIP & ISIN data. This field will be null by default for new customers. For existing customers, this field will be null by default starting on Sept 15, 2023. If you would like access to this field, please contact your Plaid Account Manager or reach out to investments-vendors@plaid.com.
sedol
nullablestring
7-character SEDOL, an identifier assigned to securities in the UK.
institution_security_id
nullablestring
An identifier given to the security by the institution
institution_id
nullablestring
If institution_security_id is present, this field indicates the Plaid institution_id of the institution to whom the identifier belongs.
proxy_security_id
nullablestring
In certain cases, Plaid will provide the ID of another security whose performance resembles this security, typically when the original security has low volume, or when a private security can be modeled with a publicly traded security.
name
nullablestring
A descriptive name for the security, suitable for display.
ticker_symbol
nullablestring
The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available.
is_cash_equivalent
nullableboolean
Indicates that a security is a highly liquid asset and can be treated like cash.
type
nullablestring
The security type of the holding. Valid security types are:
cash: Cash, currency, and money market funds
cryptocurrency: Digital or virtual currencies
derivative: Options, warrants, and other derivative instruments
equity: Domestic and foreign equities
etf: Multi-asset exchange-traded investment funds
fixed income: Bonds and certificates of deposit (CDs)
loan: Loans and loan receivables
mutual fund: Open- and closed-end vehicles pooling funds of multiple investors
other: Unknown or other investment types
close_price
nullablenumber
Price of the security at the close of the previous trading session. Null for non-public securities.
If the security is a foreign currency this field will be updated daily and will be priced in USD.
If the security is a cryptocurrency, this field will be updated multiple times a day. As crypto prices can fluctuate quickly and data may become stale sooner than other asset classes, refer to update_datetime with the time when the price was last updated.

Format: double
close_price_as_of
nullablestring
Date for which close_price is accurate. Always null if close_price is null.

Format: date
update_datetime
nullablestring
Date and time at which close_price is accurate, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). Always null if close_price is null.

Format: date-time
iso_currency_code
nullablestring
The ISO-4217 currency code of the price given. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the security. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
item
object
Metadata about the Item.
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
nullablestring
The Plaid Institution ID associated with the Item. Field is null for Items created via Same Day Micro-deposits.
webhook
nullablestring
The URL registered to receive webhooks for the Item.
error
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
available_products
[string]
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
billed_products
[string]
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available_products. Note - billed_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
products
[string]
A list of initialized products for the Item. In almost all cases, this will be the same as the billed_products field. For some products, it is possible for the product to be initialized on an Item but not yet billed (e.g. Assets, before /asset_report/create has been called), in which case the product may appear in products but not in billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consented_products
[string]
A list of products that have gone through consent collection for the Item. Only present for those enabled in the Data Transparency beta. If you are not enrolled in Data Transparency, this field is not used.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consent_expiration_time
nullablestring
The RFC 3339 timestamp after which the consent provided by the end user will expire. Upon consent expiration, the item will enter the ITEM_LOGIN_REQUIRED error state. To circumvent the ITEM_LOGIN_REQUIRED error and maintain continuous consent, the end user can reauthenticate via Link’s update mode in advance of the consent expiration time.
Note - This is only relevant for certain OAuth-based institutions. For all other institutions, this field will be null.

Format: date-time
update_type
string
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication.
background - Item can be updated in the background
user_present_required - Item requires user interaction to be updated

Possible values: background, user_present_required
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "accounts": [
3    {
4      "account_id": "5Bvpj4QknlhVWk7GygpwfVKdd133GoCxB814g",
5      "balances": {
6        "available": 43200,
7        "current": 43200,
8        "iso_currency_code": "USD",
9        "limit": null,
10        "unofficial_currency_code": null
11      },
12      "mask": "4444",
13      "name": "Plaid Money Market",
14      "official_name": "Plaid Platinum Standard 1.85% Interest Money Market",
15      "subtype": "money market",
16      "type": "depository"
17    },
18    {
19      "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
20      "balances": {
21        "available": null,
22        "current": 110.01,
23        "iso_currency_code": "USD",
24        "limit": null,
25        "unofficial_currency_code": null
26      },
27      "mask": "5555",
28      "name": "Plaid IRA",
29      "official_name": null,
30      "subtype": "ira",
31      "type": "investment"
32    },
33    {
34      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
35      "balances": {
36        "available": null,
37        "current": 23631.9805,
38        "iso_currency_code": "USD",
39        "limit": null,
40        "unofficial_currency_code": null
41      },
42      "mask": "6666",
43      "name": "Plaid 401k",
44      "official_name": null,
45      "subtype": "401k",
46      "type": "investment"
47    },
48    {
49      "account_id": "ax0xgOBYRAIqOOjeLZr0iZBb8r6K88HZXpvmq",
50      "balances": {
51        "available": 48200.03,
52        "current": 48200.03,
53        "iso_currency_code": "USD",
54        "limit": null,
55        "unofficial_currency_code": null
56      },
57      "mask": "4092",
58      "name": "Plaid Crypto Exchange Account",
59      "official_name": null,
60      "subtype": "crypto exchange",
61      "type": "investment"
62    }
63  ],
64  "holdings": [
65    {
66      "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
67      "cost_basis": 1,
68      "institution_price": 1,
69      "institution_price_as_of": "2021-04-13",
70      "institution_price_datetime": null,
71      "institution_value": 0.01,
72      "iso_currency_code": "USD",
73      "quantity": 0.01,
74      "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",
75      "unofficial_currency_code": null
76    },
77    {
78      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
79      "cost_basis": 1.5,
80      "institution_price": 2.11,
81      "institution_price_as_of": "2021-04-13",
82      "institution_price_datetime": null,
83      "institution_value": 2.11,
84      "iso_currency_code": "USD",
85      "quantity": 1,
86      "security_id": "KDwjlXj1Rqt58dVvmzRguxJybmyQL8FgeWWAy",
87      "unofficial_currency_code": null
88    },
89    {
90      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
91      "cost_basis": 10,
92      "institution_price": 10.42,
93      "institution_price_as_of": "2021-04-13",
94      "institution_price_datetime": null,
95      "institution_value": 20.84,
96      "iso_currency_code": "USD",
97      "quantity": 2,
98      "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
99      "unofficial_currency_code": null
100    },
101    {
102      "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
103      "cost_basis": 0.01,
104      "institution_price": 0.011,
105      "institution_price_as_of": "2021-04-13",
106      "institution_price_datetime": null,
107      "institution_value": 110,
108      "iso_currency_code": "USD",
109      "quantity": 10000,
110      "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
111      "unofficial_currency_code": null
112    },
113    {
114      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
115      "cost_basis": 23,
116      "institution_price": 27,
117      "institution_price_as_of": "2021-04-13",
118      "institution_price_datetime": null,
119      "institution_value": 636.309,
120      "iso_currency_code": "USD",
121      "quantity": 23.567,
122      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
123      "unofficial_currency_code": null
124    },
125    {
126      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
127      "cost_basis": 15,
128      "institution_price": 13.73,
129      "institution_price_as_of": "2021-04-13",
130      "institution_price_datetime": null,
131      "institution_value": 1373.6865,
132      "iso_currency_code": "USD",
133      "quantity": 100.05,
134      "security_id": "nnmo8doZ4lfKNEDe3mPJipLGkaGw3jfPrpxoN",
135      "unofficial_currency_code": null
136    },
137    {
138      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
139      "cost_basis": 1,
140      "institution_price": 1,
141      "institution_price_as_of": "2021-04-13",
142      "institution_price_datetime": null,
143      "institution_value": 12345.67,
144      "iso_currency_code": "USD",
145      "quantity": 12345.67,
146      "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",
147      "unofficial_currency_code": null
148    },
149    {
150      "account_id": "ax0xgOBYRAIqOOjeLZr0iZBb8r6K88HZXpvmq",
151      "cost_basis": 92.47,
152      "institution_price": 0.177494362,
153      "institution_price_as_of": "2022-01-14",
154      "institution_price_datetime": "2022-06-07T23:01:00Z",
155      "institution_value": 4437.35905,
156      "iso_currency_code": "USD",
157      "quantity": 25000,
158      "security_id": "vLRMV3MvY1FYNP91on35CJD5QN5rw9Fpa9qOL",
159      "unofficial_currency_code": null
160    }
161  ],
162  "item": {
163    "available_products": [
164      "balance",
165      "identity",
166      "liabilities",
167      "transactions"
168    ],
169    "billed_products": [
170      "assets",
171      "auth",
172      "investments"
173    ],
174    "consent_expiration_time": null,
175    "error": null,
176    "institution_id": "ins_3",
177    "item_id": "4z9LPae1nRHWy8pvg9jrsgbRP4ZNQvIdbLq7g",
178    "update_type": "background",
179    "webhook": "https://www.genericwebhookurl.com/webhook"
180  },
181  "request_id": "l68wb8zpS0hqmsJ",
182  "securities": [
183    {
184      "close_price": 0.011,
185      "close_price_as_of": "2021-04-13",
186      "cusip": null,
187      "institution_id": null,
188      "institution_security_id": null,
189      "is_cash_equivalent": false,
190      "isin": null,
191      "iso_currency_code": "USD",
192      "name": "Nflx Feb 01'18 $355 Call",
193      "proxy_security_id": null,
194      "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
195      "sedol": null,
196      "ticker_symbol": "NFLX180201C00355000",
197      "type": "derivative",
198      "unofficial_currency_code": null,
199      "update_datetime": null
200    },
201    {
202      "close_price": 27,
203      "close_price_as_of": null,
204      "cusip": "577130834",
205      "institution_id": null,
206      "institution_security_id": null,
207      "is_cash_equivalent": false,
208      "isin": "US5771308344",
209      "iso_currency_code": "USD",
210      "name": "Matthews Pacific Tiger Fund Insti Class",
211      "proxy_security_id": null,
212      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
213      "sedol": null,
214      "ticker_symbol": "MIPTX",
215      "type": "mutual fund",
216      "unofficial_currency_code": null,
217      "update_datetime": null
218    },
219    {
220      "close_price": 2.11,
221      "close_price_as_of": null,
222      "cusip": "00448Q201",
223      "institution_id": null,
224      "institution_security_id": null,
225      "is_cash_equivalent": false,
226      "isin": "US00448Q2012",
227      "iso_currency_code": "USD",
228      "name": "Achillion Pharmaceuticals Inc.",
229      "proxy_security_id": null,
230      "security_id": "KDwjlXj1Rqt58dVvmzRguxJybmyQL8FgeWWAy",
231      "sedol": null,
232      "ticker_symbol": "ACHN",
233      "type": "equity",
234      "unofficial_currency_code": null,
235      "update_datetime": null
236    },
237    {
238      "close_price": 10.42,
239      "close_price_as_of": null,
240      "cusip": "258620103",
241      "institution_id": null,
242      "institution_security_id": null,
243      "is_cash_equivalent": false,
244      "isin": "US2586201038",
245      "iso_currency_code": "USD",
246      "name": "DoubleLine Total Return Bond Fund",
247      "proxy_security_id": null,
248      "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
249      "sedol": null,
250      "ticker_symbol": "DBLTX",
251      "type": "mutual fund",
252      "unofficial_currency_code": null,
253      "update_datetime": null
254    },
255    {
256      "close_price": 1,
257      "close_price_as_of": null,
258      "cusip": null,
259      "institution_id": null,
260      "institution_security_id": null,
261      "is_cash_equivalent": true,
262      "isin": null,
263      "iso_currency_code": "USD",
264      "name": "U S Dollar",
265      "proxy_security_id": null,
266      "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",
267      "sedol": null,
268      "ticker_symbol": "USD",
269      "type": "cash",
270      "unofficial_currency_code": null,
271      "update_datetime": null
272    },
273    {
274      "close_price": 13.73,
275      "close_price_as_of": null,
276      "cusip": null,
277      "institution_id": "ins_3",
278      "institution_security_id": "NHX105509",
279      "is_cash_equivalent": false,
280      "isin": null,
281      "iso_currency_code": "USD",
282      "name": "NH PORTFOLIO 1055 (FIDELITY INDEX)",
283      "proxy_security_id": null,
284      "security_id": "nnmo8doZ4lfKNEDe3mPJipLGkaGw3jfPrpxoN",
285      "sedol": null,
286      "ticker_symbol": "NHX105509",
287      "type": "etf",
288      "unofficial_currency_code": null,
289      "update_datetime": null
290    },
291    {
292      "close_price": 0.140034616,
293      "close_price_as_of": "2022-01-24",
294      "cusip": null,
295      "institution_id": "ins_3",
296      "institution_security_id": null,
297      "is_cash_equivalent": true,
298      "isin": null,
299      "iso_currency_code": "USD",
300      "name": "Dogecoin",
301      "proxy_security_id": null,
302      "security_id": "vLRMV3MvY1FYNP91on35CJD5QN5rw9Fpa9qOL",
303      "sedol": null,
304      "ticker_symbol": "DOGE",
305      "type": "cryptocurrency",
306      "unofficial_currency_code": null,
307      "update_datetime": "2022-06-07T23:01:00Z"
308    }
309  ]
310}
Was this helpful?

/investments/transactions/get

Get investment transactions

The /investments/transactions/get endpoint allows developers to retrieve up to 24 months of user-authorized transaction data for investment accounts.
Transactions are returned in reverse-chronological order, and the sequence of transaction ordering is stable and will not shift.
Due to the potentially large number of investment transactions associated with an Item, results are paginated. Manipulate the count and offset parameters in conjunction with the total_investment_transactions response body field to fetch all available investment transactions.
Note that Investments does not have a webhook to indicate when initial transaction data has loaded (unless you use the async_update option). Instead, if transactions data is not ready when /investments/transactions/get is first called, Plaid will wait for the data. For this reason, calling /investments/transactions/get immediately after Link may take up to one to two minutes to return.
Data returned by the asynchronous investments extraction flow (when async_update is set to true) may not be immediately available to /investments/transactions/get. To be alerted when the data is ready to be fetched, listen for the HISTORICAL_UPDATE webhook. If no investments history is ready when /investments/transactions/get is called, it will return a PRODUCT_NOT_READY error.

investments/transactions/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
start_date
requiredstring
The earliest date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD.

Format: date
end_date
requiredstring
The most recent date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD.

Format: date
options
object
An optional object to filter /investments/transactions/get results. If provided, must be non-null.
account_ids
[string]
An array of account_ids to retrieve for the Item.
count
integer
The number of transactions to fetch.

Default: 100
Minimum: 1
Maximum: 500
offset
integer
The number of transactions to skip when fetching transaction history

Default: 0
Minimum: 0
async_update
boolean
If the Item was not initialized with the investments product via the products array when calling /link/token/create, and async_update is set to true, the initial Investments extraction will happen asynchronously. Plaid will subsequently fire a HISTORICAL_UPDATE webhook when the extraction completes. When false, Plaid will wait to return a response until extraction completion and no HISTORICAL_UPDATE webhook will fire. Note that while the extraction is happening asynchronously, calls to /investments/transactions/get and /investments/refresh will return PRODUCT_NOT_READY errors until the extraction completes.

Default: false
Select group for content switcher
Select Language
1const request: InvestmentsTransactionsGetRequest = {
2  access_token: accessToken,
3  start_date: '2019-01-01',
4  end_date: '2019-06-10',
5};
6try {
7  const response = await plaidClient.investmentsTransactionsGet(request);
8  const investmentTransactions = response.data.investment_transactions;
9} catch (error) {
10  // handle error
11}
investments/transactions/get

Response fields and example

item
object
Metadata about the Item.
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
nullablestring
The Plaid Institution ID associated with the Item. Field is null for Items created via Same Day Micro-deposits.
webhook
nullablestring
The URL registered to receive webhooks for the Item.
error
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
available_products
[string]
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
billed_products
[string]
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available_products. Note - billed_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
products
[string]
A list of initialized products for the Item. In almost all cases, this will be the same as the billed_products field. For some products, it is possible for the product to be initialized on an Item but not yet billed (e.g. Assets, before /asset_report/create has been called), in which case the product may appear in products but not in billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consented_products
[string]
A list of products that have gone through consent collection for the Item. Only present for those enabled in the Data Transparency beta. If you are not enrolled in Data Transparency, this field is not used.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consent_expiration_time
nullablestring
The RFC 3339 timestamp after which the consent provided by the end user will expire. Upon consent expiration, the item will enter the ITEM_LOGIN_REQUIRED error state. To circumvent the ITEM_LOGIN_REQUIRED error and maintain continuous consent, the end user can reauthenticate via Link’s update mode in advance of the consent expiration time.
Note - This is only relevant for certain OAuth-based institutions. For all other institutions, this field will be null.

Format: date-time
update_type
string
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication.
background - Item can be updated in the background
user_present_required - Item requires user interaction to be updated

Possible values: background, user_present_required
accounts
[object]
The accounts for which transaction history is being fetched.
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullablenumber
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullablenumber
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullablenumber
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullablestring
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
securities
[object]
All securities for which there is a corresponding transaction being fetched.
security_id
string
A unique, Plaid-specific identifier for the security, used to associate securities with holdings. Like all Plaid identifiers, the security_id is case sensitive. The security_id may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change.
isin
nullablestring
12-character ISIN, a globally unique securities identifier. Please note that Plaid's customers must hold a license directly from CUSIP Global Services to receive CUSIP & ISIN data. This field will be null by default for new customers. For existing customers, this field will be null by default starting on Sept 15, 2023. If you would like access to this field, please contact your Plaid Account Manager or reach out to investments-vendors@plaid.com.
cusip
nullablestring
9-character CUSIP, an identifier assigned to North American securities. Please note that Plaid's customers must hold a license directly from CUSIP Global Services to receive CUSIP & ISIN data. This field will be null by default for new customers. For existing customers, this field will be null by default starting on Sept 15, 2023. If you would like access to this field, please contact your Plaid Account Manager or reach out to investments-vendors@plaid.com.
sedol
nullablestring
7-character SEDOL, an identifier assigned to securities in the UK.
institution_security_id
nullablestring
An identifier given to the security by the institution
institution_id
nullablestring
If institution_security_id is present, this field indicates the Plaid institution_id of the institution to whom the identifier belongs.
proxy_security_id
nullablestring
In certain cases, Plaid will provide the ID of another security whose performance resembles this security, typically when the original security has low volume, or when a private security can be modeled with a publicly traded security.
name
nullablestring
A descriptive name for the security, suitable for display.
ticker_symbol
nullablestring
The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available.
is_cash_equivalent
nullableboolean
Indicates that a security is a highly liquid asset and can be treated like cash.
type
nullablestring
The security type of the holding. Valid security types are:
cash: Cash, currency, and money market funds
cryptocurrency: Digital or virtual currencies
derivative: Options, warrants, and other derivative instruments
equity: Domestic and foreign equities
etf: Multi-asset exchange-traded investment funds
fixed income: Bonds and certificates of deposit (CDs)
loan: Loans and loan receivables
mutual fund: Open- and closed-end vehicles pooling funds of multiple investors
other: Unknown or other investment types
close_price
nullablenumber
Price of the security at the close of the previous trading session. Null for non-public securities.
If the security is a foreign currency this field will be updated daily and will be priced in USD.
If the security is a cryptocurrency, this field will be updated multiple times a day. As crypto prices can fluctuate quickly and data may become stale sooner than other asset classes, refer to update_datetime with the time when the price was last updated.

Format: double
close_price_as_of
nullablestring
Date for which close_price is accurate. Always null if close_price is null.

Format: date
update_datetime
nullablestring
Date and time at which close_price is accurate, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). Always null if close_price is null.

Format: date-time
iso_currency_code
nullablestring
The ISO-4217 currency code of the price given. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the security. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
investment_transactions
[object]
The transactions being fetched
investment_transaction_id
string
The ID of the Investment transaction, unique across all Plaid transactions. Like all Plaid identifiers, the investment_transaction_id is case sensitive.
cancel_transaction_id
deprecatednullablestring
A legacy field formerly used internally by Plaid to identify certain canceled transactions.
account_id
string
The account_id of the account against which this transaction posted.
security_id
nullablestring
The security_id to which this transaction is related.
date
string
The ISO 8601 posting date for the transaction.

Format: date
name
string
The institution’s description of the transaction.
quantity
number
The number of units of the security involved in this transaction. Positive for buy transactions; negative for sell transactions.

Format: double
amount
number
The complete value of the transaction. Positive values when cash is debited, e.g. purchases of stock; negative values when cash is credited, e.g. sales of stock. Treatment remains the same for cash-only movements unassociated with securities.

Format: double
price
number
The price of the security at which this transaction occurred.

Format: double
fees
nullablenumber
The combined value of all fees applied to this transaction

Format: double
type
string
Value is one of the following: buy: Buying an investment sell: Selling an investment cancel: A cancellation of a pending transaction cash: Activity that modifies a cash position fee: A fee on the account transfer: Activity which modifies a position, but not through buy/sell activity e.g. options exercise, portfolio transfer
For descriptions of possible transaction types and subtypes, see the Investment transaction types schema.

Possible values: buy, sell, cancel, cash, fee, transfer
subtype
string
For descriptions of possible transaction types and subtypes, see the Investment transaction types schema.

Possible values: account fee, adjustment, assignment, buy, buy to cover, contribution, deposit, distribution, dividend, dividend reinvestment, exercise, expire, fund fee, interest, interest receivable, interest reinvestment, legal fee, loan payment, long-term capital gain, long-term capital gain reinvestment, management fee, margin expense, merger, miscellaneous fee, non-qualified dividend, non-resident tax, pending credit, pending debit, qualified dividend, rebalance, return of principal, request, sell, sell short, send, short-term capital gain, short-term capital gain reinvestment, spin off, split, stock distribution, tax, tax withheld, trade, transfer, transfer fee, trust fee, unqualified gain, withdrawal
iso_currency_code
nullablestring
The ISO-4217 currency code of the transaction. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the holding. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
total_investment_transactions
integer
The total number of transactions available within the date range specified. If total_investment_transactions is larger than the size of the transactions array, more transactions are available and can be fetched via manipulating the offset parameter.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "accounts": [
3    {
4      "account_id": "5e66Dl6jNatx3nXPGwZ7UkJed4z6KBcZA4Rbe",
5      "balances": {
6        "available": 100,
7        "current": 110,
8        "iso_currency_code": "USD",
9        "limit": null,
10        "unofficial_currency_code": null
11      },
12      "mask": "0000",
13      "name": "Plaid Checking",
14      "official_name": "Plaid Gold Standard 0% Interest Checking",
15      "subtype": "checking",
16      "type": "depository"
17    },
18    {
19      "account_id": "KqZZMoZmBWHJlz7yKaZjHZb78VNpaxfVa7e5z",
20      "balances": {
21        "available": null,
22        "current": 320.76,
23        "iso_currency_code": "USD",
24        "limit": null,
25        "unofficial_currency_code": null
26      },
27      "mask": "5555",
28      "name": "Plaid IRA",
29      "official_name": null,
30      "subtype": "ira",
31      "type": "investment"
32    },
33    {
34      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
35      "balances": {
36        "available": null,
37        "current": 23631.9805,
38        "iso_currency_code": "USD",
39        "limit": null,
40        "unofficial_currency_code": null
41      },
42      "mask": "6666",
43      "name": "Plaid 401k",
44      "official_name": null,
45      "subtype": "401k",
46      "type": "investment"
47    }
48  ],
49  "investment_transactions": [
50    {
51      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
52      "amount": -8.72,
53      "cancel_transaction_id": null,
54      "date": "2020-05-29",
55      "fees": 0,
56      "investment_transaction_id": "oq99Pz97joHQem4BNjXECev1E4B6L6sRzwANW",
57      "iso_currency_code": "USD",
58      "name": "INCOME DIV DIVIDEND RECEIVED",
59      "price": 0,
60      "quantity": 0,
61      "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ",
62      "subtype": "dividend",
63      "type": "cash",
64      "unofficial_currency_code": null
65    },
66    {
67      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
68      "amount": -1289.01,
69      "cancel_transaction_id": null,
70      "date": "2020-05-28",
71      "fees": 7.99,
72      "investment_transaction_id": "pK99jB9e7mtwjA435GpVuMvmWQKVbVFLWme57",
73      "iso_currency_code": "USD",
74      "name": "SELL Matthews Pacific Tiger Fund Insti Class",
75      "price": 27.53,
76      "quantity": -47.74104242992852,
77      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
78      "subtype": "sell",
79      "type": "sell",
80      "unofficial_currency_code": null
81    },
82    {
83      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
84      "amount": 7.7,
85      "cancel_transaction_id": null,
86      "date": "2020-05-27",
87      "fees": 7.99,
88      "investment_transaction_id": "LKoo1ko93wtreBwM7yQnuQ3P5DNKbKSPRzBNv",
89      "iso_currency_code": "USD",
90      "name": "BUY DoubleLine Total Return Bond Fund",
91      "price": 10.42,
92      "quantity": 0.7388014749727547,
93      "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
94      "subtype": "buy",
95      "type": "buy",
96      "unofficial_currency_code": null
97    }
98  ],
99  "item": {
100    "available_products": [
101      "assets",
102      "balance",
103      "identity",
104      "transactions"
105    ],
106    "billed_products": [
107      "auth",
108      "investments"
109    ],
110    "consent_expiration_time": null,
111    "error": null,
112    "institution_id": "ins_12",
113    "item_id": "8Mqq5rqQ7Pcxq9MGDv3JULZ6yzZDLMCwoxGDq",
114    "update_type": "background",
115    "webhook": "https://www.genericwebhookurl.com/webhook"
116  },
117  "request_id": "iv4q3ZlytOOthkv",
118  "securities": [
119    {
120      "close_price": 27,
121      "close_price_as_of": null,
122      "cusip": "577130834",
123      "institution_id": null,
124      "institution_security_id": null,
125      "is_cash_equivalent": false,
126      "isin": "US5771308344",
127      "iso_currency_code": "USD",
128      "name": "Matthews Pacific Tiger Fund Insti Class",
129      "proxy_security_id": null,
130      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
131      "sedol": null,
132      "ticker_symbol": "MIPTX",
133      "type": "mutual fund",
134      "unofficial_currency_code": null,
135      "update_datetime": null
136    },
137    {
138      "close_price": 10.42,
139      "close_price_as_of": null,
140      "cusip": "258620103",
141      "institution_id": null,
142      "institution_security_id": null,
143      "is_cash_equivalent": false,
144      "isin": "US2586201038",
145      "iso_currency_code": "USD",
146      "name": "DoubleLine Total Return Bond Fund",
147      "proxy_security_id": null,
148      "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
149      "sedol": null,
150      "ticker_symbol": "DBLTX",
151      "type": "mutual fund",
152      "unofficial_currency_code": null,
153      "update_datetime": null
154    },
155    {
156      "close_price": 34.73,
157      "close_price_as_of": null,
158      "cusip": "84470P109",
159      "institution_id": null,
160      "institution_security_id": null,
161      "is_cash_equivalent": false,
162      "isin": "US84470P1093",
163      "iso_currency_code": "USD",
164      "name": "Southside Bancshares Inc.",
165      "proxy_security_id": null,
166      "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ",
167      "sedol": null,
168      "ticker_symbol": "SBSI",
169      "type": "equity",
170      "unofficial_currency_code": null,
171      "update_datetime": null
172    }
173  ],
174  "total_investment_transactions": 3
175}
Was this helpful?

Webhooks

Updates are sent to indicate that new holdings or investment transactions are available.

HOLDINGS: DEFAULT_UPDATE

Fired when new or updated holdings have been detected on an investment account. The webhook typically fires in response to any newly added holdings or price changes to existing holdings, most commonly after market close.

webhook_type
string
HOLDINGS
webhook_code
string
DEFAULT_UPDATE
item_id
string
The item_id of the Item associated with this webhook, warning, or error
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
new_holdings
number
The number of new holdings reported since the last time this webhook was fired.
updated_holdings
number
The number of updated holdings reported since the last time this webhook was fired.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "HOLDINGS",
3  "webhook_code": "DEFAULT_UPDATE",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "error": null,
6  "new_holdings": 19,
7  "updated_holdings": 0,
8  "environment": "production"
9}
Was this helpful?

INVESTMENTS_TRANSACTIONS: DEFAULT_UPDATE

Fired when new transactions have been detected on an investment account.

webhook_type
string
INVESTMENTS_TRANSACTIONS
webhook_code
string
DEFAULT_UPDATE
item_id
string
The item_id of the Item associated with this webhook, warning, or error
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
new_investments_transactions
number
The number of new transactions reported since the last time this webhook was fired.
canceled_investments_transactions
number
The number of canceled transactions reported since the last time this webhook was fired.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "INVESTMENTS_TRANSACTIONS",
3  "webhook_code": "DEFAULT_UPDATE",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "error": null,
6  "new_investments_transactions": 16,
7  "canceled_investments_transactions": 0,
8  "environment": "production"
9}
Was this helpful?

INVESTMENTS_TRANSACTIONS: HISTORICAL_UPDATE

Fired after an asynchronous extraction on an investments account.

webhook_type
string
INVESTMENTS_TRANSACTIONS
webhook_code
string
HISTORICAL_UPDATE
item_id
string
The item_id of the Item associated with this webhook, warning, or error
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
new_investments_transactions
number
The number of new transactions reported since the last time this webhook was fired.
canceled_investments_transactions
number
The number of canceled transactions reported since the last time this webhook was fired.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "INVESTMENTS_TRANSACTIONS",
3  "webhook_code": "HISTORICAL_UPDATE",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "error": null,
6  "new_investments_transactions": 16,
7  "canceled_investments_transactions": 0,
8  "environment": "production"
9}
Was this helpful?

errors item

Item Errors

Guide to troubleshooting Item errors

ACCESS_NOT_GRANTED

The user did not grant necessary permissions for their account.
Sample user-facing error message
Insufficient Sharing Permissions: There was an error connecting to your account. Try linking your account again by selecting the required information to share with this application.
Common causes
  • This Item's access is affected by institution-hosted access controls.
  • The user did not agree to share, or has revoked, access to the data required for the requested product. Note that for some institutions, the end user may need to specifically opt-in during the OAuth flow to share specific details, such as identity data, or account and routing number information, even if they have already opted in to sharing information about a specific account.
  • The user does not have permission to share required information about the account. This can happen at some institutions using OAuth connections if the user is not the account owner (for example, they have a role such as trustee, investment advisor, power of attorney holder, or authorized cardholder).
Troubleshooting steps
1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "ACCESS_NOT_GRANTED",
5 "error_message": "access to this product was not granted for the account",
6 "display_message": "The user did not grant the necessary permissions for this product on their account.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INSTANT_MATCH_FAILED

Instant Match could not be initialized for the Item.
Common causes
  • Instant Auth could not be used for the Item, and Instant Match has been enabled for your account, but a country other than US is specified in Link's country code initialization.
  • The Item does not support Instant Auth or Instant Match. If this is the case, Plaid will automatically attempt to enter a micro-deposit based verification flow.
Troubleshooting steps
1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "INSTANT_MATCH_FAILED",
5 "error_message": "Item cannot be verified through Instant Match. Ensure you are correctly enabling all auth features in Link.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INSUFFICIENT_CREDENTIALS

The user did not provide sufficient authorization in order to link their account via an OAuth login flow.
Sample user-facing error message
Access Denied: The authorization flow did not complete
Common causes
  • Your user abandoned the bank OAuth flow without completing it.
Troubleshooting steps

If this error persists, please submit a Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "INSUFFICIENT_CREDENTIALS",
5 "error_message": "insufficient authorization was provided to complete the request",
6 "display_message": "INSUFFICIENT_CREDENTIALS",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_CREDENTIALS

The financial institution indicated that the credentials provided were invalid.
Sample user-facing error message
The credentials you provided were incorrect: Check that your credentials are the same that you use for this institution
Link user experience

Your user will be redirected to the Credentials pane to retry entering correct credentials.

Common causes
  • The user entered incorrect credentials at their selected institution.
    • Extra spaces, capitalization, and punctuation errors are common causes of INVALID_CREDENTIALS.
  • The institution requires special configuration steps before the user can link their account with Plaid. KeyBank and Betterment are two examples of institutions that require this setup.
  • The user selected the wrong institution.
    • Plaid supports institutions that have multiple login portals for the various products they offer, and it is common for users to confuse a different selection for the one which their credentials would actually be accepted.
    • For example: a user may have selected Fidelity instead of Fidelity - NetBenefits. This confusion is particularly common between Fidelity (brokerage accounts) and Fidelity NetBenefits (retirement accounts) and between Vanguard (brokerage accounts) and My Vanguard Plan (retirement accounts). This is also common for users attempting to link prepaid stored-value cards, as many institutions have separate login portals specifically for those cards.
Troubleshooting steps

Note: The Institution may lock a user out of their account after 3-5 repeated attempts, resulting in an ITEM_LOCKED error.

If the credentials are confirmed to be legitimate, and a user still cannot authenticate, please submit an 'Invalid credentials errors' Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "INVALID_CREDENTIALS",
5 "error_message": "the provided credentials were not correct",
6 "display_message": "The provided credentials were not correct. Please try again.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_MFA: OTP Device & Code

The institution indicated that the provided response for the selected device and OTP code was invalid.
Sample user-facing error message
Security code incorrect: Check that the code you entered is the same code that was sent to you
Link user experience

Your user will be redirected to the MFA Device pane to reselect their multi-factor authentication device and re-enter their one-time code.

Common causes
  • The user selected an MFA device that is not active.
  • The institution failed to send the one-time code for the user's selected device.
Troubleshooting steps

If the user does not receive a one-time code or still cannot succeed with a current MFA device login, please submit a 'Invalid credentials errors' Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "INVALID_MFA",
5 "error_message": "the provided MFA response(s) were not correct",
6 "display_message": "The provided MFA responses were not correct. Please try again.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_MFA: Questions

The institution indicated that the provided response for MFA Questions was invalid.
Sample user-facing error message
Answer incorrect: Try answering your security question again
Link user experience

Your user will be redirected to the MFA Questions pane to retry entering the correct answer.

Common causes
  • The user entered an incorrect answer for the security question presented by the selected institution.
Troubleshooting steps

If the user still cannot log in despite providing correct answers to their security questions, please submit a 'Invalid credentials errors' Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "INVALID_MFA",
5 "error_message": "the provided MFA response(s) were not correct",
6 "display_message": "The provided MFA responses were not correct. Please try again.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_MFA: Selections

The institution indicated that the provided response for MFA Selections was invalid.
Sample user-facing error message
Answer incorrect: Try answering your security questions again
Link user experience

Your user will be redirected to the MFA Selections pane to retry selecting the correct answers.

Common causes
  • The user provided an incorrect answer to the security question.
Troubleshooting steps
1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "INVALID_MFA",
5 "error_message": "the provided MFA response(s) were not correct",
6 "display_message": "The provided MFA responses were not correct. Please try again.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_SEND_METHOD

Returned when the method used to send MFA credentials was deemed invalid by the institution.
Link user experience

Your user will be shown an error message indicating that an internal error occurred and will be prompted to close Link.

Common causes
  • The institution is experiencing login issues.
  • The integration between Plaid and the financial institution is experiencing errors.
Troubleshooting steps

If the error persists, submit a 'Multi-factor authentication issues' Support ticket with the following identifiers: institution_id and either link_session_id or request_id.

1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "INVALID_SEND_METHOD",
5 "error_message": "the provided MFA send_method was invalid",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INVALID_UPDATED_USERNAME

The username entered during update mode did not match the original username.
Sample user-facing error message
Error: Try entering your bank account username again. If you recently changed it, you may need to un-link your account and then re-link.
Link user experience

Your user will be directed to enter a different username.

Common causes
  • While linking an account in update mode, the user provided a username that doesn't match the original username provided when they originally linked the account.
Troubleshooting steps
1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "INVALID_UPDATED_USERNAME",
5 "error_message": "the username provided to /item/credentials/update does not match the original username for the item",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

ITEM_CONCURRENTLY_DELETED

This item was deleted while the operation was in progress.
Common causes
  • An Item was deleted via /item/remove while a request for its data was in process.
Troubleshooting steps
1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "ITEM_CONCURRENTLY_DELETED",
5 "error_message": "This item was deleted while the operation was in progress",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

ITEM_LOCKED

The financial institution indicated that the user's account is locked. The user will need to work with the institution directly to unlock their account.
Sample user-facing error message
Too many attempts: Your account is locked for security reasons. Reset your bank username and password, and then try again.
Link user experience

Your user will be directed to a new window with the institution's homepage to unlock their account. Link will then display the Institution Select pane for the user to connect a different account.

Common causes
  • The user entered their credentials incorrectly after more than 3-5 attempts, triggering the institution’s fraud protection systems and locking the user’s account.
Troubleshooting steps

If the user is persistently locked out of their institution, submit an 'Invalid credentials errors' Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "ITEM_LOCKED",
5 "error_message": "the account is locked. prompt the user to visit the institution's site and unlock their account",
6 "display_message": "The given account has been locked by the financial institution. Please visit your financial institution's website to unlock your account.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

ITEM_LOGIN_REQUIRED

The financial institution indicated that the user's password or MFA information has changed. They will need to reauthenticate via Link's update mode.
Sample user-facing error message
Username or password incorrect: If you've recently updated your account with this institution, be sure you're entering your updated credentials
Developer experience

This error is frequently encountered during a /[product]/get request.

Common causes
  • The user changed their password.
  • The user changed their multi-factor authentication device, questions, or answers.
  • The Item's associated multi-factor authentication token has expired.
  • The institution updated its multi-factor security protocols.
  • The institution uses an OAuth-based connection and the user's access-consent is no longer valid, either because it has expired, or because the user revoked access.
  • The institution uses an OAuth-based connection that does not allow duplicate Items, but the user connected a duplicate Item to the same application.
Troubleshooting steps

If the error is legitimate, having the user authenticate again should generally return their Item to a healthy state without further intervention.

If this error persists, please submit a Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "ITEM_LOGIN_REQUIRED",
5 "error_message": "the login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

ITEM_NOT_FOUND

The Item you requested cannot be found. This Item does not exist, has been previously removed via /item/remove, or has had access removed by the user
Common causes
  • Item was previously removed via /item/remove.
  • The user has depermissioned or deleted their Item via my.plaid.com.
  • Plaid support has deleted the Item in response to a data deletion request from the user.
Troubleshooting steps
1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "ITEM_NOT_FOUND",
5 "error_message": "The Item you requested cannot be found. This Item does not exist, has been previously removed via /item/remove, or has had access removed by the user.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

ITEM_NOT_SUPPORTED

Plaid is unable to support this user's accounts due to restrictions in place at the financial institution.
Sample user-facing error message
Account not currently supported: Your account is not currently supported. Please log in using a different account
Link user experience

Your user will be redirected to the Institution Select pane to connect a different account.

Common causes
  • Plaid does not currently support the types of accounts for the the connected Item, due to restrictions in place at the selected institution.
  • Plaid does not currently support the specific type of multi-factor authentication in place at the selected institution.
  • The credentials provided are for a 'guest' account or other account type with limited account access.
Troubleshooting steps

If the error persists and none of the common causes above seem to apply, contact Support.

1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "ITEM_NOT_SUPPORTED",
5 "error_message": "this account is currently not supported",
6 "display_message": "The given account is not currently supported for this financial institution. We apologize for the inconvenience.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

MFA_NOT_SUPPORTED

Returned when the user requires a form of MFA that Plaid does not support for a given financial institution.
Sample user-facing error message
Your account settings are incompatible: Your account could not be connected because the multi-factor authentication method it uses is not currently supported. Please try a different account.
Link user experience

Your user will be redirected to the Institution Select pane to connect a different account.

Common causes
  • Plaid does not currently support the specific type of multi-factor authentication in place at the selected institution.
  • The user's multi-factor authentication setting is configured not to remember trusted devices and instead to present a multi-factor challenge on every login attempt. This prevents Plaid from refreshing data asynchronously, which many products (especially Transactions) require.
Troubleshooting steps

If user's settings are not configured to present a multi-factor challenge on every login attempt but this error is still appearing, submit a 'Multi-factor authentication issues' Support ticket with the following identifiers: institution_id and either link_session_id or request_id.

1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "MFA_NOT_SUPPORTED",
5 "error_message": "this account requires a MFA type that we do not currently support for the institution",
6 "display_message": "The multi-factor security features enabled on this account are not currently supported for this financial institution. We apologize for the inconvenience.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

NO_ACCOUNTS

Returned when there are no open accounts associated with the Item.
Sample user-facing error message
No compatible accounts: Your credentials are correct, but we couldn’t find any accounts with this institution that are compatible with this application. Try another account, financial institution, or check for another connection method.
Link user experience

Your user will be redirected to the Institution Select pane to connect a different account.

Common causes
  • The user successfully logged into their account, but Plaid was unable to retrieve any open, active, or eligible accounts in the connected Item.
  • The user closed their account.
  • The user revoked access to the account.
  • The account experienced account churn, which happens when Plaid can no longer recognize an account as the same one that the user granted you access to. When this happens, your permissions to the account may be revoked.
Troubleshooting steps

If this error persists and the user does have accounts at the institution that you should be able to access, please submit a Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "NO_ACCOUNTS",
5 "error_message": "no valid accounts were found for this item",
6 "display_message": "No valid accounts were found at the financial institution. Please visit your financial institution's website to confirm accounts are available.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

NO_AUTH_ACCOUNTS or no-depository-accounts

Returned from POST /auth/get when there are no valid checking or savings account(s) for which account and routing numbers could be retrieved.
Sample user-facing error message
No eligible accounts: We didn't find any checking or savings accounts at this institution. Please try linking another institution
Common causes
  • /auth/get was called on an Item with no accounts that can support Auth, or accounts that do support Auth were filtered out. Only debitable checking and savings accounts can be used with Auth.
  • Plaid's ability to retrieve Auth data from the institution has been temporarily disrupted.
  • The end user is connecting to an institution that uses OAuth-based flows but did not grant permission in the OAuth flow for the institution to share details for any debitable checking and savings accounts. Note that for some institutions, the end user may need to specifically opt-in during the OAuth flow to share account and routing number information even if they have already opted in to sharing information about their checking or savings account.
  • The end user revoked access to the account.
  • The account experienced account churn, which happens when Plaid can no longer recognize an account as the same one that the user granted you access to. When this happens, your permissions to the account may be revoked.
Troubleshooting steps

If the problem persists even though the end user has confirmed that they have a debitable checking or savings account at the institution, open a support ticket.

1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "NO_AUTH_ACCOUNTS",
5 "error_message": "There are no valid checking or savings account(s) associated with this Item. See https://plaid.com/docs/api/#item-errors for more.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

NO_INVESTMENT_ACCOUNTS

Returned from POST /investments/holdings/get, POST /investments/transactions/get, or Link initialized with the Investments product, when there are no valid investment account(s) for which holdings or transactions could be retrieved.
Sample user-facing error message
No investment accounts: None of your accounts are investment accounts. Please connect using a different bank
Common causes
  • Link was initialized with the Investments product, but the user attempted to link an account with no investment accounts.
  • The /investments/holdings/get or /investments/transactions/get endpoint was called, but there are no investment accounts associated with the Item.
  • The end user is connecting to an institution that uses OAuth-based flows but did not grant permission in the OAuth flow for the institution to share details for any investment accounts.
Troubleshooting steps

If the problem persists, Plaid may be erroneously categorizing the account. If this is the case, open a support ticket.

1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "NO_INVESTMENT_ACCOUNTS",
5 "error_message": "There are no valid investment account(s) associated with this Item. See https://plaid.com/docs/api/#item-errors for more information.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

NO_INVESTMENT_AUTH_ACCOUNTS

Returned from POST /investments/holdings/get or POST /investments/transactions/get when there are no valid investment account(s) for which holdings or transactions could be retrieved.
Common causes
  • The /investments/holdings/get or /investments/transactions/get endpoint was called, but there are no investment accounts associated with the Item.
  • The end user is connecting to an institution that uses OAuth-based flows but did not grant permission in the OAuth flow for the institution to share details for any investment accounts.
Troubleshooting steps

If the problem persists, Plaid may be erroneously categorizing the account. If this is the case, open a support ticket.

1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "NO_INVESTMENT_AUTH_ACCOUNTS",
5 "error_message": "There are no valid investment account(s) associated with this Item. See https://plaid.com/docs/api/#item-errors for more information.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

NO_LIABILITY_ACCOUNTS

Returned from POST /liabilities/get when there are no valid liability account(s) for which liabilities could be retrieved.
Sample user-facing error message
No liability accounts: None of your accounts are liability accounts. Please connect using a different bank
Common causes
  • The /liabilities/get endpoint was called, but there are no supported liability accounts associated with the Item.
  • The end user is connecting to an institution that uses OAuth-based flows but did not grant permission in the OAuth flow for the institution to share details for any liabilities accounts.
Troubleshooting steps

If the problem persists, Plaid may be erroneously categorizing the account. If this is the case, open a support ticket.

1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "NO_LIABILITY_ACCOUNTS",
5 "error_message": "There are no valid liability account(s) associated with this Item. See https://plaid.com/docs/api/#item-errors for more information.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

PRODUCT_NOT_ENABLED

A requested product was not enabled for the current access token. Please ensure it is included when when initializing Link and create the Item again.
Common causes
  • You requested a product that was not enabled for the current access token. Ensure it is included when when calling /link/token/create and create the Item again.
1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "PRODUCT_NOT_ENABLED",
5 "error_message": "A requested product was not enabled for the current access token. Please ensure it is included when when initializing Link and create the Item again.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

PRODUCT_NOT_READY

Returned when a data request has been made for a product that is not yet ready.
Common causes
  • /transactions/get was called before the first 30 days of transactions data could be extracted. This typically happens if the endpoint was called within a few seconds of linking the Item. It will also happen if /transactions/get was called for the first time on an Item that was not initialized with transactions in the /link/token/create call.
  • Occasionally, this error can occur upon calling /transactions/get if Plaid's attempt to extract transactions for the Item has failed, due to a connectivity error with the financial institution, and Plaid has never successfully extracted transactions for the Item in the past. If this happens, Plaid will continue to retry the extraction at least once a day.
  • /signal/evaluate was called for the first time on a new Item before any balance data could be extracted for the Item. When called, /signal/evaluate will return a PRODUCT_NOT_READY error if cached balance data does not exist and new balance data could not be obtained after 15 seconds. For some customers who participated in the early phases of the Signal beta, /signal/evaluate will return PRODUCT_NOT_READY immediately if cached balance data is not available when /signal/evaluate is called.
  • /auth/get was called on an Item that hasn't been verified, which is possible when using micro-deposit based verification.
  • /investments/transactions/get was called before the investments data could be extracted. This typically happens when the endpoint is called with the option for async_update set to true, and called again within a few seconds of linking the Item. It will also happen if /investments/transactions/get (with async_update set to true) was called for the first time on an Item that was not initialized with investments in the /link/token/create call.
Troubleshooting steps
1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "PRODUCT_NOT_READY",
5 "error_message": "the requested product is not yet ready. please provide a webhook or try the request again later",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

PRODUCTS_NOT_SUPPORTED

Returned when a data request has been made for an Item for a product that it does not support. Use the /item/get endpoint to find out which products an Item supports.
Common causes
  • A product endpoint request was made for an Item that does not support that product.
  • A product endpoint request was made for an Item at an OAuth-based institution, but the end user did not authorize the Item for the specific product, or has revoked Plaid's access to the product. Note that for some institutions, the end user may need to specifically opt-in during the OAuth flow to share specific details, such as identity data, or account and routing number information, even if they have already opted in to sharing information about a specific account. (This usage is deprecated; see also ACCESS_NOT_GRANTED)
  • Updated accounts have been requested for an Item initialized with the Assets product, which does not support adding or updating accounts after the initial Link.
  • You are attempting to call /signal/evaluate on a non-US financial institution.
Troubleshooting steps
1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "PRODUCTS_NOT_SUPPORTED",
5 "error_message": "",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

USER_SETUP_REQUIRED

The user must log in directly to the financial institution and take some action before Plaid can access their accounts.
Sample user-facing error message
Action required with your account: Log in to your bank and update your account. Then, return to Plaid to continue.
Link user experience

Your user will be directed to a new window with the institution's homepage to unlock their account. Link will then display the Institution Select pane for the user to connect a different account.

Common causes
  • The institution requires special configuration steps before the user can link their account with Plaid. KeyBank and Betterment are two examples of institutions that require this setup.
  • The user’s account is not fully set up at their institution.
  • The institution is blocking access due to an administrative task that requires completion. This error can arise for a number of reasons, the most common being:
    • The user must agree to updated terms and conditions.
    • The user must reset their password.
    • The user must enter additional account information.
Troubleshooting steps

Ask that the user log in to the bank, and confirm whether they are presented with some form of agreement page, modal, or some other actionable task. The user should also check their bank website for special settings to allow access for third-party apps, such as a "third party application password" or "allow third party access" setting.

This can usually be done completely online, but there are some financial institutions that require the user to call a phone number, or access a physical branch.

If the user is still unable to log in to their institution, please submit a 'Invalid credentials errors' Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "USER_SETUP_REQUIRED",
5 "error_message": "the account has not been fully set up. prompt the user to visit the issuing institution's site and finish the setup process",
6 "display_message": "The given account is not fully setup. Please visit your financial institution's website to setup your account.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

USER_INPUT_TIMEOUT

The user did not complete a step in the Link flow, and it timed out.
Sample user-facing error message
Session expired: Please re-enter your information to link your accounts.
Common causes
  • Your user did not complete the account selection flow within five minutes.
Troubleshooting steps
1http code 400
2{
3 "error_type": "ITEM_ERROR",
4 "error_code": "USER_INPUT_TIMEOUT",
5 "error_message": "user must retry this operation",
6 "display_message": "The application timed out waiting for user input",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

link troubleshooting

Link errors and troubleshooting

Errors in the Link flow

Link error codes

Any errors during Link will be returned via the Link flow; for details, see the guide for your specific platform. Since any failed user attempt to log on to a financial institution for any reason, even an incorrect password, will result in a Link error, you should expect to see the occasional error during Link. In most cases, Link will guide your user through the steps required to resolve the error.

The most common case in which you will need a special flow for Link errors is the ITEM_LOGIN_REQUIRED error. For instructions on handling this error, see Updating an Item.

For more details, or if you need to troubleshoot a problem involving an error message from the API, see Item errors.

Missing institutions or "Connectivity not supported" error

Symptom
  • Your user cannot find their financial institution in Link, even though it is one of the 11,500+ institutions supported by Plaid.
  • Your user experiences a "Connectivity not supported" error message after selecting their institution in Link.
Common causes
  • The institution does not support one of the products specified in Link initialization.
  • The institution is associated with a country not specified in Link initialization.
  • The institution is associated with a country your Plaid account hasn't been enabled for.
Troubleshooting steps

Institution unhealthy

Symptom

When a user tries to connect their account, they receive a message in Link that Plaid may be experiencing connectivity issues to that institution. For more details, see Institution status in Link.

Common causes
  • Plaid's connection to the institution is down or degraded.
Troubleshooting steps

Duplicate Items

Symptom

Your user has multiple Items that seem to represent the same underlying set of accounts.

Common causes
  • The user added the same Item more than once.
Troubleshooting steps

Missing accounts

Symptom

Some of the end users' accounts are not present in the Item, or a new account added by the user does not appear in the Item.

Common causes
  • The user linked their account via an OAuth flow but did not grant your app permission to access the account, or created the account after linking the Item and did not grant your app permission to access newly created accounts.
  • The user linked their account using Account Select v2 and did not grant your app permission to access the account, or they created the account after linking the Item.
  • The user linked their account using Account Select v2 and the account is incompatible with the settings specified during the /link/token/create call. For example, if auth was one of the products specified when calling /link/token/create, accounts that do not support Auth, such as credit card accounts, will not appear on the Item.
Troubleshooting steps

Link flow is failing

Symptom

The Link flow is not working correctly for the user -- the onSuccess callback may not be sent, Link may not load, or redirects may not function correctly.

Common causes
  • Third party software, such as ad-blocking browser extensions, may be interfering with Link.
  • The end user linked their account via an OAuth flow and OAuth is not configured correctly.
Troubleshooting steps

"You may need to update your app" or "Something went wrong" error message

Symptom

After selecting a bank in Link, the user gets an error message saying "You may need to update your app in order to connect to Chase" (or another institution) or "Something went wrong".

Common causes
  • The full list of OAuth prerequisites have not been completed to enable your client id for a given institution's OAuth connection.
Troubleshooting steps

See the troubleshooting guide for the UNAUTHORIZED_INSTITUTION error.

OAuth not working

First, verify these settings before reviewing the more detailed OAuth troubleshooting guides below:

If none of the steps above resolve your problem, see the specific OAuth troubleshooting guides below. If you do not see your problem listed, or following the guide does not fix the problem, contact Support.

OAuth institutions not appearing in Link

Symptom

Institutions that use OAuth, such as Capital One or Wells Fargo, are not appearing in the Link UI.

Common causes
  • A redirect_uri or android_package_name was not specified in the call to /link/token/create.
  • The redirect URI or Android package name was not allowlisted on the Plaid Dashboard.
Troubleshooting steps

OAuth flow shows unsupported browser warning

Symptom

Upon entering their institution's OAuth flow, users see a warning that their browser is not supported.

Common causes
  • The Plaid integration is using a webview with an incorrectly configured user agent.
Troubleshooting steps

OAuth redirects not working

Symptom

Users are not being redirected back to Link after completing their institution's OAuth flow.

Common causes
Android
iOS
  • Universal Links are not correctly configured.
Troubleshooting steps
Android
iOS

signal add to app

Add Signal to your app

Learn how to add Signal support to your application

In this guide, we'll start from scratch and walk through how to use Signal to perform risk analysis on proposed ACH transactions. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, you can skip ahead to fetching Signal data.

Get Plaid API keys and complete application and company profile

If you don't already have one, you'll need to create a Plaid developer account. After creating your account, you can find your API keys under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your application profile and company profile on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the Plaid Portal. Your application profile and company profile must be completed before connecting to certain institutions in Production.

Install and initialize Plaid libraries

You can use our official server-side client libraries to connect to the Plaid API from your application:

Select group for content switcher
Select Language
1// Install via npm
2npm install --save plaid

After you've installed Plaid's client libraries, you can initialize them by passing in your client_id, secret, and the environment you wish to connect to (Sandbox, Development, or Production). This will make sure the client libraries pass along your client_id and secret with each request, and you won't need to explicitly include them in any other calls.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can obtain from the Dashboard. These code samples also demonstrate starting up a server commonly used in each framework (such as Express or Flask).

Select group for content switcher
Select Language
1// Using Express
2const express = require('express');
3const app = express();
4app.use(express.json());
5
6const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
7
8const configuration = new Configuration({
9  basePath: PlaidEnvironments.sandbox,
10  baseOptions: {
11    headers: {
12      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
13      'PLAID-SECRET': process.env.PLAID_SECRET,
14    },
15  },
16});
17
18const client = new PlaidApi(configuration);

Create an Item in Link

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the Link documentation.

Using Link, we will create a Plaid Item, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. If you want to customize Link's look and feel, you can do so from the Dashboard.

Before initializing Link, you will need to create a new link_token on the server side of your application. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the /link/token/create endpoint. Then, on the client side of your application, you'll need to initialize Link with the link_token that you just created.

Create a link_token
Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth, signal'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Install Link dependency
Select Language
1<head>
2  <title>Connect a bank</title>
3  <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
4</head>
Configure the client-side Link handler
1const linkHandler = Plaid.create({
2  token: (await $.post('/create_link_token')).link_token,
3  onSuccess: (public_token, metadata) => {
4    // Send the public_token to your app server.
5    $.post('/exchange_public_token', {
6      public_token: public_token,
7    });
8  },
9  onExit: (err, metadata) => {
10    // Optionally capture when your user exited the Link flow.
11    // Storing this information can be helpful for support.
12  },
13  onEvent: (eventName, metadata) => {
14    // Optionally capture Link flow events, streamed through
15    // this callback as your users connect an Item to Plaid.
16  },
17});
18
19linkHandler.open();

Get a persistent access_token

Next, on the server side, we need to exchange our public_token for an access_token and item_id. The access_token will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the /item/public_token/exchange endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the access_token and item_id in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. The access_token will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via /item/remove. The access_token should be stored securely, and never in client-side code. A public_token is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

Select group for content switcher
Select Language
1app.post('/api/exchange_public_token', async function (
2  request,
3  response,
4  next,
5) {
6  const publicToken = request.body.public_token;
7  try {
8    const response = await client.itemPublicTokenExchange({
9      public_token: publicToken,
10    });
11
12    // These values should be saved to a persistent database and
13    // associated with the currently signed-in user
14    const accessToken = response.data.access_token;
15    const itemID = response.data.item_id;
16
17    res.json({ public_token_exchange: 'complete' });
18  } catch (error) {
19    // handle error
20  }
21});

Fetching Signal data

Now that the authentication step is out of the way, we can begin using Signal to analyze proposed transactions.

Evaluating a proposed transaction
Select Language
1const eval_request = {
2  access_token: "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175",
3  account_id: "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
4  client_transaction_id: "txn12345",
5  amount: 123.45,
6  client_user_id: "user1234",
7  user: {
8    name: {
9      prefix: "Ms.",
10      given_name: "Jane",
11      middle_name: "Leah",
12      family_name: "Doe",
13      suffix: "Jr.",
14    },
15    phone_number: "+14152223333",
16    email_address: "jane.doe@example.com",
17    address: {
18      street: "2493 Leisure Lane",
19      city: "San Matias",
20      region: "CA",
21      postal_code: "93405-2255",
22      country: "US",
23    },
24  },
25  device: {
26    ip_address: "198.30.2.2",
27    user_agent:"Mozilla/5.0 (iPhone; CPU iPhone OS 13_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Mobile/15E148 Safari/604.1",
28  },
29  user_present: true,
30};
31
32try {
33  const eval_response = await plaidClient.signalEvaluate(eval_request);
34  const core_attributes = eval_response.data.core_attributes;
35  const scores = eval_response.data.scores;
36} catch (error) {
37  // handle error
38}

Example response data is below. (The core_attributes in the example have been truncated. In actual usage, /signal/evaluate returns over 65 core attributes.)

1{
2  "scores": {
3    "customer_initiated_return_risk": {
4      "score": 9,
5      "risk_tier": 1
6    },
7    "bank_initiated_return_risk": {
8      "score": 72,
9      "risk_tier": 7
10    }
11  },
12  "core_attributes": {
13    "days_since_first_plaid_connection": 510,
14    "plaid_connections_count_7d": 6,
15    "plaid_connections_count_30d": 7,
16    "total_plaid_connections_count": 15,
17    "is_savings_or_money_market_account": false
18  },
19  "warnings": [],
20  "request_id": "mdqfuVxeoza6mhu"
21}

If the transaction is high risk, you may also want to make a second check using Balance. Balance can retrieve real-time balance data, although it does not return data as quickly as Signal does.

If you decide to proceed with the transfer, initiate it as you normally would using Plaid Auth endpoints.

After evaluating the transfer, report your decision about whether you proceeded with the transfer back to Plaid. This will help continually improve Signal's accuracy.

Select Language
1const decision_report_request = {
2  client_transaction_id: "txn12345",
3  initiated: true,
4  days_funds_on_hold: 3,
5};
6
7try {
8  const decision_report_response = await plaidClient.signalDecisionReport(decision_report_request);
9  const decision_request_id = decision_report_response.data.request_id;
10} catch (error) {
11  // handle error
12}

Finally, if you allow a transfer that does end up returned, you can report that result back to Plaid as well:

Select Language
1const return_report_request = {
2  client_transaction_id: "txn12345",
3  return_code: "R01",
4};
5
6try {
7  const return_report_response = await plaidClient.signalReturnReport(return_report_request);
8  const request_id = return_report_response.data.request_id;
9  console.log(request_id)
10} catch (error) {
11  // handle error
12}

Next steps

If you're ready to launch to Production, see the Launch checklist.

assets waitlist hosted link

Hosted Link

An easier and faster way to integrate with Plaid

Hosted Link is an easier and faster way to integrate with Plaid. With Hosted Link, Plaid will host the Link experience and can even deliver the URL to the Link session to your customers via text or email, eliminating the need for any front-end implementation work.


Hosted Link is currently available for use with Plaid's Income & Assets products. Receive access by completing the form.

Hosted Link is designed with the following customers in mind:

  • In-store lenders: If you are predominantly an in-store lender with no app or web platform, you can reach your customers directly by emailing or texting them a link to the Assets flow.
  • Online lenders who want to decrease abandon rates: If your customers have fallen out of your application process, you can use Hosted Link to prompt them to resume the process by sending them a link to the Assets flow.

The high level Hosted Link flow is as follows:

  • Create a link_token by calling /link/token/create.
  • Create a Hosted Link session by calling /link_delivery/create and providing the link_token. Specify whether you’d like for Plaid to deliver the link via SMS or email, or whether you will deliver it yourself.
  • Plaid will send the link to the end user, or you will deliver it yourself. The Link flow will open and once the user has successfully completed it, Plaid will send a webhook to notify you.
  • Call /link_delivery/get to retrieve your access token, which can be used to call asset report endpoints (e.g. /asset_report/create).
Example of SMS flow for Hosted Link
Example of SMS flow for Hosted Link. Please note that product design and experience are subject to change.
Example of email flow for Hosted Link
Example of email flow for Hosted Link. Please note that product design and experience are subject to change.

sandbox

Sandbox Overview

Use the Sandbox to quickly develop and test your app

Sandbox overview

The Plaid Sandbox is a free and fully-featured environment for application development and testing. All Plaid functionality of both the Plaid API and Plaid Link is supported in the Sandbox environment. A variety of test accounts and institutions are available to test against, and you can create an unlimited number of test Items. Sandbox API keys can be obtained in the Plaid Dashboard.

Using Sandbox

The Sandbox can be reached by sending HTTPS POST requests to the endpoints on the sandbox.plaid.com domain. In order to use the Sandbox with a client library, specify Sandbox as your environment when initializing.

The default username/password combination for all Sandbox institutions is user_good / pass_good.

Most products can be immediately tested in Sandbox with no extra configuration. Some products, such as Payment Initiation (UK and Europe), may require your account be specially enabled. If the product you want to test against is not available in Sandbox, file a request for access ticket via the Dashboard.

Bypassing Link

When doing repeated manual tests, or for writing automated tests against Sandbox, completing the Link flow may be impractical. As an alternative, you can also create Items in Sandbox via the API, using a special Sandbox-only endpoint, /sandbox/public_token/create. This endpoint allows you to generate a public_token for an arbitrary institution ID, initial products, and test credentials.

Simulating data and events

The Sandbox provides rich test data, as well as the ability to generate your own test data. You can also simulate a number of scenarios for testing in Sandbox.

ITEM_LOGIN_REQUIRED

Update mode in Link is used to handle user logins that have become invalid (for example, due to the user changing their password at their financial institution). An Item that needs to be handled via update mode will enter the ITEM_LOGIN_REQUIRED error state. To test your update mode flow in Sandbox, you can use the /sandbox/item/reset_login endpoint to force an Item into this state. Sandbox Items will also automatically enter the ITEM_LOGIN_REQUIRED state 30 days after being created.

An example of using update mode and testing in Sandbox can be found in the Plaid Pattern sample app. Items.js illustrates how to incorporate the handling and testing of update mode using the /sandbox/item/reset_login endpoint.

MFA, reCAPTCHA, and Link errors

Multi-factor authentication, reCAPTCHA, and a number of Link failure states can all by triggered in the Sandbox by using a custom set of test credentials, using the username user_good and a specially formatted password depending on the state you would like to trigger. For details, see Test credentials.

Instant Match and micro-deposit-based Auth

While the standard Instant Auth flow does not require special configuration to test, the additional Auth flows such as Instant Match, Same-day micro-deposits, and Automated micro-deposits require more complex steps such as verifying micro-deposits or routing numbers. The Sandbox environment provides several test institutions and endpoints that can be used to verify these flows. For more details, see Testing Auth flows.

Returning user experience

The Link returning user experience can be tested in Sandbox using the name, phone number, and email address of a specific Sandbox test user. For details, see Testing RUX in Sandbox.

Webhooks

Plaid provides a special Sandbox-only endpoint, /sandbox/item/fire_webhook, that can be used to trigger DEFAULT_UPDATE, NEW_ACCOUNTS_AVAILABLE, AUTH_DATA_UPDATE, RECURRING_TRANSACTIONS_UPDATE, and SYNC_UPDATES_AVAILABLE webhooks on demand, allowing you to test that you are receiving webhooks successfully.

All webhooks that would be fired in Production or Development will also fire in Sandbox.

Testing with live data using Development

The Plaid Sandbox is one of three Plaid environments, with the other two being Development and Production. In order to test with live data, you can configure your application to use the Development environment. Unlike Sandbox, Development uses real production data and real institutions, and unlike Production, it is free to use. You may add up to a maximum of 100 Items in the Development environment. Keep in mind that Items cannot be moved between environments – Sandbox Items cannot be moved to Development, and Items created in Development cannot be moved to Production.

When you first create your Plaid developer account, it will either have pre-populated access to a very limited number of Items on Development, or no access to Development at all. In either case, you can file a request for Development access via the Dashboard; once your request has been approved, you will be able to add up to 100 live Items in the Development environment.

Some products, such as Assets and Identity, require your account to be specially enabled before testing in Development or Production. To enable your account, file a request for access ticket via the Dashboard. Also note that some products, such as Identity Verification, Monitor, and Transfer, are not supported in the Development environment.

In order to test US OAuth institutions in Development, you will first need to obtain Production approval. Once you have been approved for Production access, you can test OAuth in the Development environment.

auth partnerships prime trust

Add Prime Trust to your app

Use Prime Trust with Plaid Auth to send and receive payments!

Partnership Prime Trust logo

Overview

Plaid and Prime Trust have partnered to offer platforms, exchanges, and marketplaces a secure way to open and fund accounts. Plaid enables businesses to instantly authenticate a counter-party’s bank account, giving them the ability to retrieve account details directly from the financial institution. Prime Trust provides the building blocks for financial services. With the Account Access APIs, partners can integrate with Prime Trust’s financial infrastructure to open new accounts, send assets into custody and initiate disbursements. Prime Trust supports fast account funding through ACH and additional payment options. As part of the integration, Prime Trust customers can utilize Plaid’s APIs for real-time balance information.

To get started sign up for Plaid API keys.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Prime Trust account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Prime Trust processor_token, which allows you to quickly and securely verify a bank funding source via Prime Trust's API without having to store any sensitive banking information. Utilizing Plaid + Prime Trust enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Prime Trust in order to use the Plaid + Prime Trust integration. You'll also need to enable your Plaid account for the Prime Trust integration.

First, you will need to work with the Prime Trust team to sign up for a Prime Trust account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Prime Trust to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Prime Trust processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Prime Trust, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Prime Trust processor_token. You'll send this token to Prime Trust and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Prime Trust processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'prime_trust',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Prime Trust Production credentials prior to initiating live payment transactions in the Prime Trust API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

identity verification testing

Testing in Sandbox

Test values and options for Identity Verification

Identity Verification is not supported in Plaid's Development environment. Only Production and Sandbox are supported environments. To request access to Identity Verification in Sandbox, Request product access.

Sandbox user for Identity Verification

In Sandbox mode, Identity Verification accepts a fixed set of inputs in order to result in a successful verification.

Form FieldTest Value
Mobile number234-567-8909
First nameLeslie
Last nameKnope
Verification code11111
Address123 Main St.
CityPawnee
StateIndiana
ZIP code46001
MonthJanuary
Day18
Year1975
SSN123-45-6789

Identity verification behavior in Sandbox

Lightning checks

Lightning checks in Sandbox will be compared against the information above. To simulate different test cases and results, you can adjust your Lightning input at the attribute level (e.g. an incorrect birthdate), and set up different Identity Rules to simulate different verification results.

Document checks

Documents uploaded in Sandbox will always be interpreted as genuine (not fake) documents reflecting the name and date of birth above. Document check will pass if the data provided in the Lightning check matches this name and date of birth, and will fail otherwise.

Selfie checks

Selfie checks will not be run in Sandbox mode, even if they are enabled in your template.

AML Screening

In Sandbox, Monitor screens against a real-world dataset, so the Sandbox user will not return any screening hits. For more information, including example data you can use to trigger screening hits, see Testing Monitor.

Risk Check

The risk check is fully functional in Sandbox. It’s common to trigger high risk scores when testing. For more information and advice, see Risk rules for testing.

Auto-fill

Auto-fill behavior is fully functional in Sandbox.

Financial Account Matching

Financial Account Matching is fully functional in Sandbox. If you want to change the Identity data that is being compared to the Identity Verification session, see how to create Sandbox test data.

Risk rules for testing

Many common testing behaviors (e.g. attempting to enter the Identity Verification flow repeatedly on the same device using different credentials) may be flagged as risky behavior and cause your verification attempt to fail. For testing purposes, you can temporarily set the Acceptable Risk Level for any checks you are failing to High, under the Rulesets -> Risk Rules section of the template editor. Make sure to set the Acceptable Risk Level back to your desired setting before launching in Production.

link customization

Link customization

Learn how to customize the Link UI for your app

Link customization overview

You have the ability to customize multiple parts of the Link UI from the Plaid developer Dashboard.

Screenshot of Link customization overview page

You can create multiple Link customizations in order to show different versions of Link to different users. For example, you can show an English-configured customization to users who have set their language to English, and a French-configured customization to users who have set their language to French.

To create a customization, access the Link menu within the Plaid developer Dashboard and select Link Customization. You can then create a new customization by clicking on the drop-down menu in the upper right and selecting Create new customization. Or, to create a customization based on an existing customization, open the settings pane, accessible via the gear icon in the upper-right corner of the Link customization page, and use the Duplicate button. From the settings pane, you can also modify the countries and languages the customization applies to, as well as change its name.

Screenshot of Link customization pane

To use a customization, set the link_customization_name parameter to the customization name when calling /link/token/create.

In order for a customization to be applied, the language and country settings in Link must exactly match those specified in the customization. For example, a customization with the country set to United States and Canada will not be applied if the country_codes setting provided to /link/token/create is ['US']; it must be ['US', 'CA'].

Link customization settings

Via the dashboard, you can configure the following settings:

Account Select

The Account Select pane is a required pane where users indicate which accounts they want to share data for.

This pane can be configured to allow for single account selection, multi account selection, or all accounts preselected. Your use case may influence the setting you want to choose:

  • If your Plaid use case is banking, consumer payments, or wealth, we recommend that you use the "Enabled for one account" or the "Enabled for multiple accounts" view behavior.
  • If your Plaid use case is personal financial management or lending, you may prefer to use the "Enabled for all accounts" view behavior. When a user connects their account via a financial institution’s OAuth flow, the Account Select pane may be skipped if Plaid determines that the flow has already fulfilled the account selection step (e.g. if Link is customized to enable multiple accounts to be selected and the financial institution’s OAuth flow supports this step, Plaid’s Account Select pane will not be shown).

Note that if you have enabled multi account selection or all accounts selected, this behavior may be overridden in Link during Link flows that do not support the usage of multiple accounts. For example, the Instant Match Auth flow requires the user to enter the account and routing number for a specific account, and can only be used with one account at a time. In these cases, Link will present a single account selection flow, regardless of your customization settings.

After a user selects their accounts and clicks Continue, the Connected pane will be shown. The selected accounts will be specified in the accounts property of the onSuccess() callback.

1const onSuccess = useCallback<PlaidLinkOnSuccess>(
2 (public_token: string, metadata: PlaidLinkOnSuccessMetadata) => {
3   // updated selected account ids
4   const account_ids = metadata.accounts.map(account => account.id);
5   // ...
6 },
7 [],
8);

Note that only the data for the selected accounts will be available for the accounts via the API. You can listen for NEW_ACCOUNTS_AVAILABLE webhooks to discover new accounts for the created Item and use update mode with Account Select enabled to request data to be shared for new accounts from your users.

Language and country

You can select the language Link will appear in, as well as the countries it should support, on the settings pane, accessible via the gear icon in the upper-right corner. The list of countries selected will control which institutions are displayed in Link, as well as whether the OAuth pane will appear. The language setting will determine the default strings used in the Link UI. If you want to customize the translation, you can edit the strings, as described in the Text strings section above.

Language and country are also specified via /link/token/create, using the country_codes and language parameters. It is important that the /link/token/create parameters and customization settings match each other. If the language specified via language does not match the language selected for the customization, the customization will not be applied. If the country codes specified via country_codes do not match the country codes selected for the customization, the country codes selected for the customization may be overridden.

Plaid supports over a dozen languages and countries in Link and is continually adding more. For an up-to-date list of supported languages and countries, see the Dashboard or the API Reference.

Color scheme

You can configure the color scheme used by Link to match your company's brand colors or website color scheme via the Background Color setting.

Text strings

You can change the text shown on some of the screens to customize the wording to your app. This setting can be configured via the Consent, Institution Select, Institution Search, Connected and Re-Connected settings.

Financial institutions

Plaid recommends a default list of financial institutions whose logos are shown on the bank selection screen. This list is personalized based on user data, such as location. This option is automatically enabled; the Automatic option is pre-selected in the Institution Select setting.

Alternatively, you can customize the list of institutions by choosing the Custom option, but this option may result in lower conversion.

(Document Income only) Document upload settings

If you are using the Document Income product, you can use Link customizations to individually enable or disable the different types of documents your customers are allowed to upload in Link. Document types that can be configured are: pay stubs, W-2, 1099-MISC, and 1099-K. Note that you must have Production access to Document Income before you can configure this setting; it will not appear if your Production access request has not yet been submitted or approved.

Consent pane customizations

Overview

The Consent pane is what users see when first entering Plaid Link and where they consent to the end-user privacy policy. Plaid now offers the option to select whether Plaid branding or a combination of your branding and Plaid’s is featured. This latter option includes the ability to upload a brand color as well as a brand logo.

Headlines are standardized based on which products Link is initialized with.

Product-mapped titles
Product(s)Title text
assets, auth, identity, investments, liabilities, transactions[App name] uses Plaid to connect your [custom field]
employment (beta)[App name] uses Plaid to verify your employment
income_verification[App name] uses Plaid to verify your income

This version of the Consent pane is only available to Link customization settings targeting the US and Canada.

Customizing the Consent pane

To customize the Consent pane, go to your Link customization or create a new one (you may duplicate an existing customization by using the duplicate feature):

Within the configuration page, you can choose to activate the new Plaid-branded Consent pane or the co-branded Consent pane.

If you choose the co-branded experience, you will see a box that will guide you to choosing your logo, and if you wish, a brand color that will be used for the dots animation on the loading screen. You must upload a logo (1024 x 1024 png file) to use the co-branded experience. You can upload a logo or brand color directly within the Consent experience:

Or you can make the same changes within the Team Settings page:

You can also choose to enable Data Transparency Messaging (beta) in the Consent Pane where you can describe your use case for accessing the data types that you are requesting.

Note that enabling Data Transparency Messaging on the Consent Pane will prevent your access to products beyond those that you pass to Link. For more information, see Enabling Data Transparency Messaging.

Once you are done configuring your new Consent pane, click Publish and your new changes will go into effect.

Other customizable settings

Several other settings exist to configure Link, outside of the customization pane.

Account subtype filters

Account filters allow you to select which account types and subtypes will be available in Link. For example, if you only want users to link a checking account, you can use Link to display only Items that contain checking accounts. This setting will apply to both the Account Select view and the Institution Select view.

Account filters can be configured via the account_filters parameter when creating a Link token. For details, see /link/token/create. If you are using a legacy public-key implementation instead, account filters can be configured during Link initialization using the accountSubtypes parameter. For details, see Maintaining a legacy public-key integration.

Account types and subtypes that are not compatible with the products used to initialize Link will be automatically omitted and do not require an account filter setting. For details on account type and subtype compatibility, see the Account type / product support matrix.

Returning user experience

The returning user experience can be enabled to create a streamlined Link experience for users who have already connected a financial account with Plaid. To learn more, see Returning user experience.

Institution Select shortcut

The Institution Select shortcut can be enabled to create a streamlined Link experience for users when you already know which institution the user wants to connect to before initializing Link. For example, this could be the case when migrating to Plaid from an ACH implementation where users manually entered their account and routing number.

You can pass routing_number into the institution_data request field in the /link/token/create endpoint. The matched institution will be listed first in the default list of institutions shown for that session.

If the end user chooses the matched institution, Plaid will send the MATCHED_SELECT_INSTITUTION event callback with metadata {match_reason: routing_number}.

account security

Plaid developer dashboard account security

Learn how to protect your Plaid dashboard account

Password resets

To reset your password, log in to the Plaid Dashboard, then access the Personal Security page, which contains a password reset screen.

If you ever forget your password to your Plaid Dashboard account, use the Password reset button on the login page to reset your password. You will only be able to receive your password reset email if you have verified your Plaid email address. If your email address is unverified, search your email for a message from no-reply@plaid.com with the subject line "Confirm your email" and click on the link in that email to verify your address. You should then be able to reset your password.

Two-factor authentication

Plaid allows you to enable two-factor authentication for your dashboard account via either text message or app-based authentication. After you enable two-factor authentication, you’ll be prompted to enter an authentication code each time you sign in. When you enable two-factor authentication, Plaid will show you a backup recovery code. Be sure to write down the recovery code and store it in a safe place, since it will only be displayed once.

To check whether your team members have enabled two-factor authentication, you can visit the Team Members page, where your team members' status will be displayed as "2FA ON", "2FA OFF", or "PENDING".

SSO login

Plaid offers SSO (single sign-on) login to the Plaid Dashboard as an additional feature for certain eligible plan types. We support all major identity providers, including Okta, Google Workspaces, OneLogin, and over 30 others. If you're interested in using SSO for the Dashboard, contact your Plaid account manager for more information.

Rotating keys

If your secret is ever compromised, you should rotate it from the Keys section of the Dashboard. Clicking the Rotate secret button will generate a new secret, which you can then copy and test. The old secret will still remain active until you delete it by clicking the Delete button.

Deleting accounts

To delete your Plaid Dashboard account, contact Support. Note that deleting your account is irreversible.

A Plaid Dashboard account is different from a Plaid account at my.plaid.com. To manage the financial information you're sharing via Plaid, visit my.plaid.com.

payment initiation add to app

Add Payment Initiation to your app

Learn how to use Payment Initiation for account funding in your application

In this guide, we start from scratch and walk through how to set up a Payment Initiation flow for account funding.

Payment Initiation flow overview

The Plaid flow begins when your user wants to initiate a payment to fund their account.
Step diagram
1Your backend sets up the payment and creates a payment_initiation link_token by interfacing with Plaid endpoints. It then passes the temporary token to your client app.
Step 1 diagram
2Your client app uses the link_token to initiate a Link flow for your user. The onSuccess callback signals that the payment has been initiated.
Step 2 diagram
3Your backend listens for PAYMENT_STATUS_UPDATE webhooks to keep track of the payment's status.
Step 3 diagram

For a high-level overview of all our payment related offerings, see the Introduction to Payment Initiation.

Get Plaid API keys and complete application and company profile

If you don't already have one, you'll need to create a Plaid developer account. After creating your account, you can find your API keys under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your application profile and company profile on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the Plaid Portal, and must be completed before connecting to certain institutions.

Access Payment Initiation

Payment Initiation is enabled in Sandbox by default. It uses test data and does not interact with financial institutions. You'll need to request access to Payment Initiation before using it in either Development or Production. To get access to Payment Initiation, submit a product access request Support ticket.

Install and initialize Plaid libraries

You can use our official server-side client libraries to connect to the Plaid API from your application:

Select group for content switcher
Select Language
1// Install via npm
2npm install --save plaid

After you've installed Plaid's client libraries, you can initialize them by passing in your client_id, secret, and the environment you wish to connect to (Sandbox, Development, or Production). This will make sure the client libraries pass along your client_id and secret with each request, and you won't need to include them in any other calls.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can get from the Dashboard. These code samples also show starting up a server used in each framework (such as Express or Flask).

Select group for content switcher
Select Language
1// Using Express
2const express = require('express');
3const app = express();
4app.use(express.json());
5
6const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
7
8const configuration = new Configuration({
9  basePath: PlaidEnvironments.sandbox,
10  baseOptions: {
11    headers: {
12      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
13      'PLAID-SECRET': process.env.PLAID_SECRET,
14    },
15  },
16});
17
18const client = new PlaidApi(configuration);

Setting up the payment

Before we jump into the code, let's see an overview of the steps needed to set up your payment with Plaid:

1Your app collects information of the sender and the recipient, as well as the payment amount.
Step 1 diagram
2With this information, create a recipient and obtain a recipient_id. You can reuse this recipient_id for future payments.
Step 2 diagram
3Provide the recipient_id to Plaid when you create a payment. Store the resulting payment_id along with your payment metadata.
Step 3 diagram
4From your backend, use the payment_id to create a link_token.
Step 4 diagram
5Finally, pass the link_token to your client app to initialize Link.
Step 5 diagram
Create a recipient

Before beginning the payment initiation process, you will need to know the name and account information of the recipient. With this information in hand, you can then call /payment_initiation/recipient/create to create a payment recipient and receive a recipient_id. You can later reuse this recipient_id for future payments to the same account.

Select group for content switcher
Select Language
1const { PaymentInitiationRecipientCreateRequest } = require('plaid');
2
3// Using BACS, without IBAN or address
4const request: PaymentInitiationRecipientCreateRequest = {
5 name: 'John Doe',
6 bacs: {
7    account: '26207729',
8    sort_code: '560029',
9  },
10};
11try {
12 const response = await plaidClient.paymentInitiationRecipientCreate(request);
13 const recipientID = response.data.recipient_id;
14} catch (error) {
15 // handle error
16}
Create a payment

Now that you have the recipient_id, you can provide it together with the payment amount to /payment_initiation/payment/create, which returns a payment_id.

Select group for content switcher
Select Language
1const { PaymentInitiationPaymentCreateRequest } = require('plaid');
2
3const request: PaymentInitiationPaymentCreateRequest = {
4 recipient_id: recipientID,
5 reference: 'TestPayment',
6 amount: {
7    currency: 'GBP',
8    value: 100.0,
9  },
10};
11try {
12 const response = await plaidClient.paymentInitiationPaymentCreate(request);
13 const paymentID = response.data.payment_id;
14 const status = response.data.status;
15} catch (error) {
16 // handle error
17}

Make sure to store the payment_id in your backend together with your own metadata (e.g. your internal user_id). You can use this later to process the payment status updates

Create a link_token

Before initializing Link, you need to create a new link_token on the server side of your application. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the /link/token/create endpoint. Then, on the client side of your application, you'll need to initialize Link with the link_token that you created. This will bring up the Payment Initiation flow in Link that allows your end user to confirm the payment.

When calling /link/token/create to create a token for use with Payment Initiation, you provide the payment_id and specify payment_initiation as the product.

While it is possible to initialize Link with many products, payment_initiation cannot be specified along with any other products and must be the only product in Link's product array if it is being used.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can get from the Dashboard.

Select group for content switcher
Select Language
1// Using Express
2app.post('/api/create_link_token', async function (request, response) {
3  const configs = {
4    user: {
5      // This should correspond to a unique id for the current user.
6      client_user_id: 'user-id',
7    },
8    client_name: 'Plaid Test App',
9    products: [Products.PaymentInitiation],
10    language: 'en',
11    webhook: 'https://webhook.sample.com',
12    country_codes: [CountryCode.Gb],
13    payment_initiation: {
14      payment_id: paymentID,
15    },
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(configs);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});

Once you have exposed an endpoint to create a link_token in your application server, you now need to configure your client application to import and use Link.

Launch the Payment Initiation flow in Link

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for the many financial institutions that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Because Link has access to all the details of the payment at the time of initialization, it will display a screen with the payment details already populated. All your end user has to do is log in to their financial institution through a Link-initiated OAuth flow, select a funding account, and confirm the payment details.

Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the Link documentation. If you want to customize Link's look and feel, you can do so from the Dashboard.

Install Link dependency
Select Language
1<head>
2 <title>Link for Payment Initiation</title>
3 <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
4</head>
Configure the client-side Link handler

Plaid communicates to you certain events that relate to how the user is interacting with Link. What you do with each of these event triggers depends on your particular use case, but a basic scaffolding might look like this:

1const linkHandler = Plaid.create({
2  // Create a new link_token to initialize Link
3  token: (await $.post('/create_link_token')).link_token,
4  onSuccess: (public_token, metadata) => {
5      // Show a success page to your user confirming that the
6      // payment will be processed.
7      //
8      // The 'metadata' object contains info about the institution
9      // the user selected.
10      // For example:
11      //  metadata  = {
12      //    link_session_id: "123-abc",
13      //    institution: {
14      //      institution_id: "ins_117243",
15      //      name:"Monzo"
16      //    }
17      //  }
18    },
19  onExit: (err, metadata) => {
20      // The user exited the Link flow.
21      if (err != null) {
22        // The user encountered a Plaid API error prior to exiting.
23      }
24      // 'metadata' contains information about the institution
25      // that the user selected and the most recent API request IDs.
26      // Storing this information can be helpful for support.
27  },
28  onEvent: (eventName, metadata) => {
29    // Optionally capture Link flow events, streamed through
30    // this callback as your users connect with Plaid.
31    // For example:
32    //  eventName = "TRANSITION_VIEW",
33    //  metadata  = {
34    //    link_session_id: "123-abc",
35    //    mfa_type:        "questions",
36    //    timestamp:       "2017-09-14T14:42:19.350Z",
37    //    view_name:       "MFA",
38    //  }
39  },
40});
41
42linkHandler.open();

Unlike other products, for payment_initiation it is not necessary to exchange the public_token for an access_token. You only need the payment_id to interact with the payment_initiation endpoints.

Verify payment status

Listening for status update webhooks

Once the payment has been authorised by the end user and the Link flow is completed, the onSuccess callback is invoked, signaling that the payment status is now PAYMENT_STATUS_INITIATED.

From this point on, you can track the payment status using a webhook that is triggered by Plaid when updates occur:

  1. Updates are sent by Plaid to the configured webhook URL to indicate that the status of an initiated payment has changed. All Payment Initiation webhooks have a webhook_type of PAYMENT_INITIATION.

  2. Once you receive the status update, use the payment_id field to retrieve the payment's metadata from your database.

  3. From the status update object, use the new_payment_status field to the decide what action needs to be taken for this payment. For example, you may decide to fund the account once the payment status is PAYMENT_STATUS_EXECUTED or notify the user that their payment got rejected (PAYMENT_STATUS_REJECTED).

For more information on how to implement your webhook listener, see the webhooks documentation.

The EXECUTED status indicates that funds have left the payer’s account, but it doesn’t offer absolute assurance that funds will settle. If you require strong settlement guarantees, Plaid provides Payment Confirmation through the Virtual Accounts product.

Generally, payments settle within seconds with instant payment schemes. However, settlement may take one business day or more when slower payment schemes are selected. The most common payment schemes and their settlement times are:

  • Faster Payment System: An instant payment scheme used in the UK. The money is usually available in the receiving customer’s account almost immediately, although it can sometimes take up to two hours.
  • SEPA Instant Credit Transfer: A pan-European instant payment scheme. Under the SEPA Instant Credit Transfer rules, funds will made available on the account in less than ten seconds.
  • SEPA Credit Transfer: A pan-European payment scheme where payments are processed and settled within one business day.
Polling for status updates

The status of a payment can also be retrieved using the /payment_initiation/payment/get endpoint.

Select group for content switcher
Select Language
1const { PaymentInitiationPaymentGetRequest } = require('plaid');
2
3const request: PaymentInitiationPaymentGetRequest = {
4 payment_id: paymentID,
5};
6try {
7 const response = await plaidClient.paymentInitiationPaymentGet(request);
8 const paymentID = response.data.payment_id;
9 const paymentToken = response.data.payment_token;
10 const reference = response.data.reference;
11 const amount = response.data.amount;
12 const status = response.data.status;
13 const lastStatusUpdate = response.data.last_status_update;
14 const paymentTokenExpirationTime =
15 response.data.payment_token_expiration_time;
16 const recipientID = response.data.recipient_id;
17} catch (error) {
18 // handle error
19}

Sample code in Plaid Pattern

For an example implementation of Payment Initiation, see the Payment Initiation Pattern App on GitHub, which uses Payment Initiation in an account funding use case.

Next steps

If you're ready to launch to Production, see the Launch checklist.

virtual accounts account sweeping

Account Sweeping

Sweep funds from your virtual account

Account sweeping periodically sweeps the current balance of a virtual account to a designated client-owned bank account. By default, automated account sweeping is not enabled.

Sweeping funds ensures you control how much balance you maintain in your virtual account. If a virtual account used for refunds or payouts also has account sweeping enabled, there may be requests that fail whenever a virtual account does not have sufficient funds.

Sweep funds from a Virtual Account

Make sure your virtual account is set up before following these steps. For more information on setting up an account, see Managing virtual accounts.

There are two ways you can sweep funds from your virtual account:

(Preferred) Automated

For each virtual account you want automated account sweeping to be enabled for, provide your Account Manager with:

  • The virtual account's wallet_id.

  • The account details for the designated account which funds should be swept to.

The current balance of each virtual account will be swept once a day at 12:00AM UTC indefinitely.

Manual

If you prefer to manually control account sweeping, you will need to manually execute a Payout each time you want to sweep funds.

errors recaptcha

ReCAPTCHA Errors

Guide to troubleshooting reCAPTCHA errors

RECAPTCHA_REQUIRED

The request was flagged by Plaid's fraud system, and requires additional verification to ensure they are not a bot.
Link user experience

Your user will be prompted to solve a Google reCAPTCHA challenge in the Link Recaptcha pane. If they solve the challenge successfully, the user's request is resubmitted and they are directed to the next Item creation step.

Common causes
  • Plaid's fraud system detects abusive traffic and considers a variety of parameters throughout Item creation requests. When a request is considered risky or possibly fraudulent, Link presents a reCAPTCHA for the user to solve.
Troubleshooting steps

Link will automatically guide your user through reCAPTCHA verification. As a general rule, we recommend instrumenting basic fraud monitoring to detect and protect your website from spam and abuse.

If your user cannot verify their session, please submit a Support ticket with the following identifiers: link_session_id or request_id.

1http code 400
2{
3 "error_type": "RECAPTCHA_ERROR",
4 "error_code": "RECAPTCHA_REQUIRED",
5 "error_message": "This request requires additional verification. Please resubmit the request after completing the challenge",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

RECAPTCHA_BAD

The provided challenge response was denied.
Sample user-facing error message
Please try connecting a different account: There was a problem processing your request. Your account could not be connected at this time
Link user experience

If after several failed attempts your user is still unable to solve the reCAPTCHA challenge, the RECAPTCHA_BAD error is returned and they are directed to the InstitutionSelect pane to connect a new account.

Common causes
  • The user was unable to successfully solve the presented reCAPTCHA problem after several attempts.
  • The current session is a bot or other malicious software.
Troubleshooting steps

If your user cannot verify their session, please submit a Support ticket with the following identifiers: link_session_id or request_id.

1http code 400
2{
3 "error_type": "RECAPTCHA_ERROR",
4 "error_code": "RECAPTCHA_BAD",
5 "error_message": "The provided challenge response was denied. Please try again",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

account resellers

Resellers

Create and manage your customers

The Reseller Dashboard and API are new functionality that Plaid has developed to support our authorized Reseller Partners. If you don't have a formal partnership established with Plaid, contact us to learn about signing up or to receive the appropriate contractual agreements to unlock this functionality.

Overview

This guide explains how an authorized Plaid Reseller Partner can create and manage their End Customer teams. Each one of your End Customers is required to have a unique set of Plaid API keys, which enables reporting their billable usage, filing and managing support issues, customizing their Plaid Link experience, and registering their applications with our financial institution partners.

Configuring your Reseller Partner team

When you join the Plaid Reseller Partner program, you will work with your Partner Account Manager to set up a Reseller Partner team for your company.

Get started by signing up for a Dashboard account, which will automatically create a team for you. Next, talk to your Partner Account Manager to configure your team as a Reseller Partner team.

If you already have a Plaid Dashboard account, or are using Plaid for a separate use case or business line, we require that you create a separate Reseller Partner team. You can use the same Dashboard user account (email address) to access both teams.

Methods for creating and managing End Customers

Plaid offers two ways to create and manage End Customers:

  1. The Dashboard (described in this guide)
  2. The reseller API (documented in the reseller API reference docs)

The steps described in Configuring you Reseller Partner team are required regardless of whether you use the Dashboard or the reseller API.

If you expect to onboard a large number of End Customers, or if you'd like to minimize the amount of manual work required by your operations staff, we strongly recommend that you integrate with our reseller API, which allows you to programmatically incorporate End Customer creation and management into your onboarding flows.

Whether you create End Customers programmatically via the reseller API or manually in the Dashboard, they will be visible and active in both places. For example, if you create an End Customer via the API, you will be able to view it in the Dashboard, and vice versa.

Under the hood, the reseller API and the Dashboard behave identically and follow the same onboarding process, which is described in Creating End Customers.

Viewing the Dashboard as a Reseller Partner

Being a member of a Reseller Partner team automatically grants you permission to create and manage End Customers. However, you must first switch to your Reseller Partner team in the Dashboard to exercise these permissions.

Ensure that your Reseller Partner team's name appears in the top left-hand corner of the Dashboard. If a different team's name is displayed, click the team's name to open the team switcher and then select your Reseller Partner team's name:

If your Reseller Partner team does not appear in the list (which can happen if you have a lot of End Customers), go to the Teams page and click on it there.

Creating End Customers

First, follow the instructions in Viewing the Dashboard as a Reseller Partner.

Next, select the team switcher in top left-hand corner and then click Create new team. Fill out and submit the form.

Once you have created the End Customer, it will appear in the Your End Customer teams list in the Teams page:

You can view the newly created End Customer's API keys by clicking on the End Customer and navigating to the Team Settings > Keys tab. The customer will automatically be enabled in the Sandbox and Development environments to facilitate testing.

The newly created End Customer will be assigned a status, which will change as they move through the onboarding process. The possible statuses are described below:

  • UNDER REVIEW: You successfully created the End Customer, but more information is needed before Plaid can approve or deny them. This status is most commonly seen when the newly created End Customer is already a Plaid customer, in which case you will need to talk with your Partner Account Manager to resolve the channel conflict.
  • DENIED: You successfully created the End Customer, but Plaid has determined that we cannot service them through your reseller contract. This status is most commonly seen in the case of channel conflicts (i.e., Plaid already has a contract with this End Customer).
  • PENDING ENABLEMENT: You successfully created the End Customer and Plaid has approved them. You may now enable the End Customer (see the next section, Enabling End Customers, for details on the enablement process).
  • ACTIVE: You successfully created and enabled the End Customer. The End Customer's API keys can now be used in the Production environment.

Enabling End Customers

When you create an End Customer, they will only be enabled in the Sandbox and Development environments. This allows you to test your End Customers prior to enabling them in Production. It also prevents you from accidentally incurring billable activity prior to launching with your End Customers.

To enable an End Customer, click on their team in the Overview page and then click Get production access.

Enablement happens instantly. Once the End Customer has been enabled, you will be able to view their Production secret on the Keys page and use it to make API calls to Plaid in the Production environment.

When you enable an End Customer, Plaid will automatically begin registering them with financial institutions that require OAuth access for connectivity, such as Chase and Capital One. Registration at most institutions happens within 24 hours, but for some institutions it may take several weeks. You can check the registration status for all OAuth institutions via the OAuth institutions page for a given End Customer.

Alternatively, you can set up a webhook in the dashboard to get automatically notified when an End Customer has their OAuth status updated. To configure the webhook, go to the webhooks page and create a new webhook listening to the End Customer OAuth status updated event type. For details on the webhook, see the partner API documentation.

If you encounter errors during OAuth registration, contact your Partner Account Manager for help.

Deleting End Customers

In some cases you may wish to delete an End Customer prior to enabling them for Production, possibly because they were created in error or because they are no longer working with you.

To delete an End Customer, go to the Teams page, click on the three dots next to the End Customer's name, and then click Delete team:

Deleting the End Customer will immediately deactivate their API keys and remove them from view in the Dashboard. This feature does not work for Production-enabled End Customers (those with a status of ACTIVE). To delete a Production-enabled customer, contact your Partner Account Manager.

api

API Reference

Comprehensive reference for integrating with Plaid API endpoints

Endpoint and schema overview

Plaid's API endpoints and schemas are listed below. If you are looking for reference information about client-side integrations on web or mobile, see the Link docs.

Retrieving and deleting Items
Fetching data about supported institutions
Retrieving account information and seeing all possible account types and subtypes
Obtaining and managing tokens from Link
Endpoints for use with or by Plaid partners
Endpoints for use by Plaid reseller partners
Sandbox-specific endpoints for testing
Optionally verify webhook signatures
Retrieve up to 24 months of transaction data and stay up-to-date with webhooks
Retrieve and verify bank account information
Retrieve real-time balance information
Verify users' identities and reduce fraud with the Identity product
Access users' financial information for loan underwriting
View holdings and transactions from investment accounts
Access data for student loans, mortgages, and credit cards
Initiate payments within your app
Manage the entire lifecycle of a payment
Transfer funds between bank accounts
Verify a user's income via payroll data.
Verify a user's identity.
Screen a user or entity.
Assess the return risk of an ACH debit transaction.
Send transaction data and retrieve enrichments.

API access

To gain access to the Plaid API, create an account on the Plaid developer dashboard. Once you’ve completed the signup process and acknowledged our terms, we’ll provide a live client_id and secret via the Dashboard.

API protocols and headers

The Plaid API uses POST requests to communicate and HTTP response codes to indicate status and errors. All responses come in standard JSON. The Plaid API is served over HTTPS TLS v1.2+ to ensure data privacy; HTTP and HTTPS with TLS versions below 1.2 are not supported. Clients must use an up to date root certificate bundle as the only TLS verification path; certificate pinning should never be used. All requests must include a Content-Type of application/json and the body must be valid JSON.

Almost all Plaid API endpoints require a client_id and secret. These may be sent either in the request body or in the headers PLAID-CLIENT-ID and PLAID-SECRET.

Every Plaid API response includes a request_id, either in the body or (in the case of endpoints that return binary data, such as /asset_report/pdf/get) in the response headers. For faster support, include the request_id when contacting support regarding a specific API call.

API host

Select Language
1https://sandbox.plaid.com (Sandbox)
2https://development.plaid.com (Development)
3https://production.plaid.com (Production)

Plaid has three environments: Sandbox, Development, and Production. Items, once created, cannot be moved to another environment. The Sandbox environment supports only test Items. The Development environment supports up to 100 live Items using real data. All testing should be done in the Sandbox and Development environments. All activity in the Production environment will be billed. When you’re getting ready to launch into Production, request Production API access via the dashboard.

API status and incidents

API status is available at status.plaid.com.

API status and incidents are also available programmatically via the following endpoints:

For a complete list of all API status information available programmatically, as well as more information on using these endpoints, see the Atlassian Status API documentation.

Storing API data

Any token returned by the API is sensitive and should be stored securely. Except for the public_token and link_token, all Plaid tokens are long-lasting and should never be exposed on the client side. Consumer data obtained from the Plaid API is sensitive information and should be managed accordingly. For guidance and best practices on how to store and handle sensitive data, see the Open Finance Security Data Standard.

Identifiers used by the Plaid API that do not contain consumer data and are not keys or tokens are designed for usage in less sensitive contexts. The most common of these identifiers are the account_id, item_id, link_session_id, and request_id. These identifiers are commonly used for logging and debugging purposes.

API field formats

Strings

Many string fields returned by Plaid APIs are reported exactly as returned by the financial institution. For this reason, Plaid does not have maximum length limits or standardized formats for strings returned by the API. In practice, field lengths of 280 characters will generally be adequate for storing returned strings, although Plaid does not guarantee this as a maximum string length.

Numbers and money

Plaid returns all currency values as decimal values in dollars (or the equivalent for the currency being used), rather than as integers. In some cases, it may be possible for a money value returned by the Plaid API to have more than two digits of precision -- this is common, for example, when reporting crypto balances.

OpenAPI definition file

OpenAPI is a standard format for describing RESTful APIs that allows those APIs to be integrated with tools for a wide variety of applications, including testing, client library generation, IDE integration, and more. The Plaid API is specified in our Plaid OpenAPI GitHub repo.

Postman collection

The Postman collection is a convenient tool for exploring Plaid API endpoints without writing code. The Postman collection provides pre-formatted requests for almost all of Plaid's API endpoints. All you have to do is fill in your API keys and any arguments. To get started, check out the Plaid Postman Collection Quickstart on GitHub.

Client libraries

See the client libraries page for more information on Plaid's client libraries.

assets waitlist statements

Bank Statements

Retrieve a PDF copy of a user's bank statement (beta coming soon)

Bank Statements allows you to retrieve a PDF copy of an end user's statement. The Bank Statements product simplifies the process of collecting documents for loan verification purposes or rental application review purposes, among others.

Bank Statements is currently in development, with an initial beta release scheduled for Q3 2023. To join the waitlist for the Bank Statements beta, complete the Bank Statements beta waitlist form.

The end user experience for sharing bank statements.
The end user experience for sharing bank statements.

Plaid provides the following endpoints to access statement information:

  • /statements/list: Retrieve the download URLs for the available bank statement PDFs utilizing the access token.
  • /statements/download/: Download a single bank statement in PDF format.
Sample bank statement retrieved with the Bank Statements product.
Sample bank statement retrieved with the Bank Statements product.

api products balance

Balance

API reference for Balance endpoints and webhooks

Verify real-time account balances.

Endpoints
/accounts/balance/getFetch real-time account balances

Endpoints

/accounts/balance/get

Retrieve real-time balance data

The /accounts/balance/get endpoint returns the real-time balance for each of an Item's accounts. While other endpoints may return a balance object, only /accounts/balance/get forces the available and current balance fields to be refreshed rather than cached. This endpoint can be used for existing Items that were added via any of Plaid’s other products. This endpoint can be used as long as Link has been initialized with any other product, balance itself is not a product that can be used to initialize Link. As this endpoint triggers a synchronous request for fresh data, latency may be higher than for other Plaid endpoints; if you encounter errors, you may find it necessary to adjust your timeout period when making requests.

accounts/balance/get

Request fields and example

access_token
requiredstring
The access token associated with the Item data is being requested for.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
options
object
An optional object to filter /accounts/balance/get results.
account_ids
[string]
A list of account_ids to retrieve for the Item. The default value is null.
Note: An error will be returned if a provided account_id is not associated with the Item.
min_last_updated_datetime
string
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the oldest acceptable balance when making a request to /accounts/balance/get.
If the balance that is pulled for ins_128026 (Capital One) is older than the given timestamp, an INVALID_REQUEST error with the code of LAST_UPDATED_DATETIME_OUT_OF_RANGE will be returned with the most recent timestamp for the requested account contained in the response.
This field is only used when the institution is ins_128026 (Capital One), in which case a value must be provided or an INVALID_REQUEST error with the code of INVALID_FIELD will be returned. For all other institutions, this field is ignored.

Format: date-time
Select group for content switcher
Select Language
1// Pull real-time balance information for each account associated
2// with the Item
3const request: AccountsGetRequest = {
4  access_token: accessToken,
5};
6try {
7  const response = await plaidClient.accountsBalanceGet(request);
8  const accounts = response.data.accounts;
9} catch (error) {
10  // handle error
11}
accounts/balance/get

Response fields and example

accounts
[object]
An array of financial institution accounts associated with the Item. If /accounts/balance/get was called, each account will include real-time balance information.
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullablenumber
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullablenumber
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullablenumber
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullablestring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullablestring
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
item
object
Metadata about the Item.
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
nullablestring
The Plaid Institution ID associated with the Item. Field is null for Items created via Same Day Micro-deposits.
webhook
nullablestring
The URL registered to receive webhooks for the Item.
error
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
available_products
[string]
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
billed_products
[string]
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available_products. Note - billed_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
products
[string]
A list of initialized products for the Item. In almost all cases, this will be the same as the billed_products field. For some products, it is possible for the product to be initialized on an Item but not yet billed (e.g. Assets, before /asset_report/create has been called), in which case the product may appear in products but not in billed_products.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consented_products
[string]
A list of products that have gone through consent collection for the Item. Only present for those enabled in the Data Transparency beta. If you are not enrolled in Data Transparency, this field is not used.

Possible values: assets, auth, balance, identity, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal
consent_expiration_time
nullablestring
The RFC 3339 timestamp after which the consent provided by the end user will expire. Upon consent expiration, the item will enter the ITEM_LOGIN_REQUIRED error state. To circumvent the ITEM_LOGIN_REQUIRED error and maintain continuous consent, the end user can reauthenticate via Link’s update mode in advance of the consent expiration time.
Note - This is only relevant for certain OAuth-based institutions. For all other institutions, this field will be null.

Format: date-time
update_type
string
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication.
background - Item can be updated in the background
user_present_required - Item requires user interaction to be updated

Possible values: background, user_present_required
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "accounts": [
3    {
4      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
5      "balances": {
6        "available": 100,
7        "current": 110,
8        "iso_currency_code": "USD",
9        "limit": null,
10        "unofficial_currency_code": null
11      },
12      "mask": "0000",
13      "name": "Plaid Checking",
14      "official_name": "Plaid Gold Standard 0% Interest Checking",
15      "persistent_account_id": "8cfb8beb89b774ee43b090625f0d61d0814322b43bff984eaf60386e",
16      "subtype": "checking",
17      "type": "depository"
18    },
19    {
20      "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
21      "balances": {
22        "available": null,
23        "current": 410,
24        "iso_currency_code": "USD",
25        "limit": 2000,
26        "unofficial_currency_code": null
27      },
28      "mask": "3333",
29      "name": "Plaid Credit Card",
30      "official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
31      "subtype": "credit card",
32      "type": "credit"
33    },
34    {
35      "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
36      "balances": {
37        "available": null,
38        "current": 65262,
39        "iso_currency_code": "USD",
40        "limit": null,
41        "unofficial_currency_code": null
42      },
43      "mask": "7777",
44      "name": "Plaid Student Loan",
45      "official_name": null,
46      "subtype": "student",
47      "type": "loan"
48    }
49  ],
50  "item": {
51    "available_products": [
52      "balance",
53      "identity",
54      "investments"
55    ],
56    "billed_products": [
57      "assets",
58      "auth",
59      "liabilities",
60      "transactions"
61    ],
62    "consent_expiration_time": null,
63    "error": null,
64    "institution_id": "ins_3",
65    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
66    "update_type": "background",
67    "webhook": "https://www.genericwebhookurl.com/webhook"
68  },
69  "request_id": "qk5Bxes3gDfv4F2"
70}
Was this helpful?

link react native react native v6 v7 migration

6.x to 7.x/8.x Migration Guide

Reference for migrating the Link React Native SDK from 6.x to 7.x or 8.x

Overview

This article provides a guide on how to upgrade a Plaid integration from the React Native 6.x SDK to the 7.x or 8.x SDK.

Update Android versions

In your build.gradle you no longer need to specify the sdk-core or okhttp3 dependencies.

  • Remove implementation 'com.plaid.link:sdk-core:3.2.0+'
  • Remove implementation 'com.squareup.okhttp3:okhttp:4.9.0+'

Update iOS versions

Update your Plaid pod dependency to 2.2.2 or greater.

1pod 'Plaid', '~> 2.2.2'

Update Plaid component

PlaidLink is now built with TypeScript! PlaidLink renders a Pressable component, which wraps the component you provide and intercepts onPress events to open Link. Additionally, the structure of the inputs has changed.

  • Pass in all properties using the tokenConfig
  • You must not use the oauthNonce or oauthRedirectUri

linkLogLevel has been added as an optional parameter, which can be used to output useful debugging information.

Public key integrations

Note that tokenConfig implementations are preferred to the deprecated publicKeyConfig implementation. You can migrate to a token configuration using the Link Token migration guide.

If you are using the deprecated public key integration, please be aware of these changes:

  • Pass in all properties using publicKeyConfig:
    • product has been renamed to products.
    • env has been renamed to environment.
    • oauthNonce, oauthRedirectUri and oauthStateId are now encapsulated in oauthConfiguration.
    • component and componentProps have been removed and you may now use children to pass in a component.

Update Success, Exit and Event types

The output types for Success, Exit and Event have been unified across Android and iOS.

For a full listing of changes, see the platform-specific migration guides:

Output type changes for Android

Output type changes for iOS

For the full API specifications, see the main docs.

auth partnerships solid

Add Solid to your app

Use Solid with Plaid Auth to send and receive payments!

Partnership Solid logo

Overview

Plaid and Solid have partnered to help Solid clients instantly authenticate external bank accounts for use with the Solid Platform. The integration helps Solid clients validate accounts when pulling funds on the Solid platform, whether for funding an account or accepting payments.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Solid account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Solid processor_token, which allows you to quickly and securely verify a bank funding source via Solid's API without having to store any sensitive banking information. Utilizing Plaid + Solid enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Solid in order to use the Plaid + Solid integration. You'll also need to enable your Plaid account for the Solid integration.

First, you will need to work with the Solid team to sign up for a Solid account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Solid to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Solid processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with , set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a processor_token. You'll send this token to and they will use it to securely retrieve account and routing numbers from Plaid.

You can create processor_tokens in the following API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: '',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Solid Production credentials prior to initiating live payment transactions in the Solid API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

quickstart glossary

Glossary

A glossary of Plaid terminology

Tokens, identifiers, and keys

Plaid tokens are in the format [type]-[environment]-[uuid], where the type may be public, access, link, or asset-report, and the environment may be sandbox, development, or production; a token will only ever be valid within the environment it was created. The UUID is a 32 character hexadecimal string in the pattern of 8-4-4-4-12 characters and conforms to the RFC 4122 standard.

Access token

An access_token is a token used to make API requests related to a specific Item. You will typically obtain an access_token by calling /item/public_token/exchange. For more details, see the Token exchange flow. An access_token does not expire, although it may require updating, such as when a user changes their password, or when working with European institutions that comply with PSD2's 90-day consent window. For more information, see When to use update mode. Access tokens should always be stored securely, and associated with the user whose data they represent. If compromised, an access_token can be rotated via /item/access_token/invalidate. If no longer needed, it can be revoked via /item/remove.

Asset report token

An asset_report_token is a token used to make API requests related to a specific Asset Report. You will obtain an asset_report_token by calling /asset_report/create. An asset_report_token does not expire, and should always be stored securely, and should be associated in your database with the user whose data it represents. If compromised or no longer needed, an asset_report_token can be revoked via /asset_report/remove.

Client ID

Your client_id is an identifier required by the Plaid API. It must be provided for almost all API calls. Your client ID can be found on the Dashboard. Your client ID uniquely identifies your team and will be the same for all API calls made on behalf of your organization, regardless of the API environment or the specific individual using the API.

Item ID

An item_id uniquely identifies a Plaid Item. The item_id is part of the response for API endpoints that operate on a specific Item, including most product endpoints, as well as /item/get and /item/public_token/exchange.

Link token

A link_token is a token used to initialize Link, and must be provided any time you are presenting your user with the Link interface. You can obtain a Link token by calling /link/token/create. For more details, see the the Token exchange flow. A link_token expires after 4 hours (or after 30 minutes, when being used with update mode).

Link session ID

The link_session_id is a unique ID included in all Link callbacks. For faster issue resolution, the link_session_id should be included when contacting Support regarding a specific Link session.

Payment Profile token

A payment_profile_token is a token used to store payment information and make Transfer API requests related to a specific user and set of payment information. You will obtain a payment_profile_token by calling /payment_profile/create. The token can then be initialized by providing it to /link/token/create and using the resulting Link token to initialize a Link session, which the end user then completes. A payment_profile_token does not expire, and should always be stored securely, and should be associated in your database with the user whose data it represents. If compromised or no longer needed, a payment_profile_token can be revoked via /payment_profile/remove.

Processor token

A processor_token is a token used by a Plaid partner to make API calls on your behalf. You can obtain a processor_token by calling /processor/token/create or /processor/stripe/bank_account_token/create and providing an access_token. The processor_token does not expire. Once successfully passed to the processor, it can be safely deleted from your database.

Public token

A public_token is a token obtained from Link's onSuccess callback. This token can be exchanged for an access_token by calling /item/public_token/exchange. For more details, see the Token exchange flow. A public_token expires after 30 minutes.

Request ID

A request_id is a unique ID returned as part of the response body for every Plaid API response (except for API endpoints that return binary data, in which case the request_id will be found in the header). The request_id can be used to look up the request on the Activity Log and should be included when contacting Support regarding a specific API call.

Secret

Your secret is used to authenticate calls to the Plaid API. Secrets can be found on the dashboard. Your secret should be kept secret and rotated if it is ever compromised. For more information, see rotating keys.

User token

A user_token is used when working with Plaid's Income or Employment APIs. It is used to associate income data from multiple sources with a single user and must be provided when initializing /link/token/create for an Income Verification flow. A user_token is created by calling /user/create and does not expire. Ensure that you store the user_token along with your user's identifier in your database, as it is not possible to retrieve a previously created user_token.

Environments

Development

Development (https://development.plaid.com) is one of three Plaid environments on which you can run your code, along with Sandbox and Production. Like Production, the Development environment uses real world data, but like Sandbox, API calls in Development are not billed. You can create up to 100 Items in Development, and these Items cannot be moved to Production. For more information, see Testing with live data using Development.

Production

Production (https://production.plaid.com) is one of three Plaid environments on which you can run your code, along with Sandbox and Development. While Sandbox and Development are intended as test environments, Production is intended for production code. It uses real world data, and API calls are billed.

Sandbox

The Sandbox (https://sandbox.plaid.com) is one of three Plaid environments on which you can run your code, along with Development and Production. Sandbox is a free test environment in which no real data can be used. The Sandbox environment also offers a number of special Sandbox-only capabilities to make testing easier. For more information, see Sandbox.

Other Plaid terminology

Account

An account is a single account held by a user at a financial institution; for example, a specific checking account or savings account. A user may have more than one account at a given institution; the overall object that contains all of these accounts is the Item. Each account is uniquely identified by an account_id, which will not change, unless Plaid is unable to reconcile the account with the data returned by the financial institution; for more information, see INVALID_ACCOUNT_ID.

Plaid will automatically detect when an account is closed, and will no longer return the account_id for a closed account. If an access_token is deleted, and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date, the new account_id will be different from the account_id associated with the original access_token.

Dashboard

The Dashboard, also known as the Plaid developer Dashboard, is used to manage your Plaid developer account, configure your account for OAuth, and to obtain keys and secrets. The Dashboard also contains a number of useful features, including troubleshooting tools, activity and usage logs, billing data, details and status for supported institutions, and the ability to request additional products or environments or to submit a support ticket. It can be found at dashboard.plaid.com. For more information, see Your Plaid developer account.

Item

An Item represents a login at a financial institution. A single end-user of your application might have accounts at different financial institutions, which means they would have multiple different Items. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. Each Item linked within your application will have a corresponding access_token, which is a token that you can use to make API requests related to that specific Item.

Two Items created for the same set of credentials at the same institution will be considered different and not share the same item_id.

Link

Link is Plaid's client-side, user-facing UI that allows end users to connect their financial institution account to your application. For more information, see Link.

transfer payment profiles

Connect accounts using Payment Profiles

Use Payment Profiles to store user payment information for a high-converting payment experience

Overview

A Payment Profile is a fast, simple, and high converting way for users to connect their account and manage their money securely in your app with Plaid. With a Payment Profile, a user's preferred payment information will be saved after linking their account with Plaid. The next time the user enters the Transfer flow, their Payment Profile can be re-used, allowing them to use a streamlined, higher-converting payment experience.

There are two flows that a user could encounter, depending on if the user has connected the account before. Both of these flows would result in a payment_profile_token ready to be used to initiate transfers with the Transfer API.

First time user flow

First time user flow using Payment Profile

If the user has not connected a Payment Profile before, they will encounter the first time user flow. They are prompted to select their institution, log in with their bank, and select the bank account they wish to use with Transfer. After completing the first time flow, their information will be saved to the Payment Profile.

Returning user flow

Returning user flow using Payment Profile

If the user has completed a Payment Profile connection with Plaid before, they will encounter the returning user flow. In this flow, the user is prompted to authenticate by entering a one-time passcode that’s sent to their mobile device. Once they are authenticated, they can complete the Payment Profile connection with their previously saved information.

Using Payment Profiles with Transfer

Create a Payment Profile

Call /payment_profile/create to generate a Payment Profile. Take note of the payment_profile_token field returned as you will need this for the next steps. A payment_profile_token does not expire, should always be stored securely, and should be associated in your database with the user whose data it represents.

1{
2    "payment_profile_token": "payment-profile-sandbox-5cbf270e-0cad-4f4e-836c-94a85403c3ac",
3    "request_id": "rUaB0dzz1zyJVPs"  
4}
Generate a Link token

Generate a Link token by calling /link/token/create and specifying the following:

  • "transfer" in the products array. Ensure that "transfer" is the only product being initialized.
  • A transfer object in the body of the create request. Within the object, specify the payment_profile_token using the value returned by /payment_profile/create
  • A user object in the body of the create request. Populate the phone_number field in the user object with the user’s phone number.
Select Language
1const request: LinkTokenCreateRequest = {
2  user: {
3    client_user_id: 'user-id',
4    phone_number: '+1 415 555 0123',
5  },
6  client_name: 'Plaid App',
7  products: ['transfer'],
8  country_codes: ['US'],
9  language: 'en',
10  webhook: 'https://sample-web-hook.com',
11  redirect_uri: 'https://domainname.com/oauth-page.html',
12  transfer: {
13    payment_profile_token: 'PAYMENT_PROFILE_TOKEN',
14  }
15};
16try {
17  const response = await plaidClient.linkTokenCreate(request);
18  const linkToken = response.data.link_token;
19} catch (error) {
20  // handle error
21}
Initializing Link with the generated token

Next, initialize Link using the link_token you generated. Depending on the information provided to the API or input by the user, they will either get the first time flow or the returning flow. Once the user has completed the flow, the onSuccess callback is called and the payment_profile_token is ready to be used for initiating transfers. Follow the steps in Sending or receiving funds to create a transfer.

Update Mode for Payment Profile

The authentication or authorization for a Payment Profile can become invalid: for example, this can be caused by a user changing their password at an institution that does not use OAuth. When this happens, calls made to /transfer/authorization/create will result in an authorization decision rationale of PAYMENT_PROFILE_LOGIN_REQUIRED. You can proceed with creating the transfer with this Payment Profile, but it is not recommended as Plaid was unable to collect enough data to make a thorough risk evaluation. Instead, ask the user to re-authenticate with Link in Payment Profile update mode, which will prompt the user to re-login and return the Payment Profile into a good state for subsequent transfers.

Removing the Payment Profile

If the user has indicated they no longer wish to save the payment information, call /payment_profile/remove to remove the Payment Profile and prevent further transfers.

Testing Payment Profiles in Sandbox

Real phone numbers do not work in the Plaid Sandbox. Instead, the Sandbox has been seeded with a test user whose phone number might be used to trigger a returning user flow. Use the special phone number +14155550234 in /link/token/create to test the returning user flow in Sandbox:

1curl -X POST https://sandbox.plaid.com/link/token/create -H 'Content-Type: application/json' -d '{
2  "client_id": "CLIENT_ID",
3  "secret": "SECRET",
4  "user": {
5    "client_user_id": "unique-per-user",
6    "phone_number": "+1 415 555 0234"
7  },
8  "client_name": "Plaid App",
9  "products": ["transfer"],
10  "country_codes": ["US"],
11  "language": "en",
12  "webhook": "https://sample-web-hook.com",
13  "redirect_uri": "https://domainname.com/oauth-page.html",
14  "transfer": {
15    "payment_profile_token": "PAYMENT_PROFILE_TOKEN"
16  }
17}'

The valid OTP code sent to this user is always 123456.

Welcome to the Docs

Here you'll find guides, resources, and references to build with Plaid.

Explore Products

Explore by use case

Bank onboarding
Auth to fetch account ACH info for money movement
Balance to fetch real-time account balances and avoid overdrafts
Identity to reduce fraud and complement KYC procedures
Income to verify income and employment
Transfer to transfer funds between accounts
Identity Verification to verify user identity for KYC
Monitor to screen customers against AML watchlists
Signal to assess the return risk of an ACH debit transaction
Consumer and peer-to-peer payments
Auth to fetch account ACH info for money movement
Balance to fetch real-time account balances and avoid overdrafts
Identity to reduce fraud and complement KYC procedures
Identity Verification to verify user identity for KYC
Monitor to screen customers against AML watchlists
Transfer to transfer funds between accounts
Signal to assess the return risk of an ACH debit transaction
Financial management and wealth management tools
Transactions to fetch detailed transaction history
Liabilities to fetch loan and debt details
Investments to fetch investment holdings and transactions details
Loan underwriting and servicing
Assets to verify borrowers' assets and transaction history
Liabilities to get information about outstanding loans
Income to verify income and employment
Identity to confirm customer information and reduce fraud
Balance to fetch real-time account balances and avoid overdrafts on loan payments
Auth to fetch account ACH info for money movement
Identity Verification to verify user identity for KYC
Monitor to screen customers against AML watchlists
Bill payments and business finances
Auth to fetch account ACH info for payroll, invoicing, and reimbursements
Balance to fetch real-time account balances and avoid overdrafts
Transactions to fetch transaction history and find reimbursable expenses
Transfer to transfer funds between accounts

auth partnerships alpaca

Add Alpaca to your app

Use Alpaca with Plaid Auth to send and receive payments!

Partnership Alpaca logo

Overview

Plaid and Alpaca have partnered to offer Alpaca’s Broker API partners seamless authentication and funding. Alpaca made it easier than ever to integrate zero-commission stock market trading directly into your application, offer your users a universe of US equities including ETFs and fractionals. Using this integration, bank accounts connected via Plaid can be added to the Alpaca platform in a simple way.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Alpaca account to add a bank funding source.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment transactions. From there, you'll receive a Plaid access_token and a Alpaca processor_token, which allows you to quickly and securely verify a bank funding source via Alpaca's API without having to store any sensitive banking information. Utilizing Plaid + Alpaca enables a seamless workflow for sending and receiving payments.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Alpaca in order to use the Plaid + Alpaca integration. You'll also need to enable your Plaid account for the Alpaca integration.

First, you will need to work with the Alpaca team to sign up for a Alpaca account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Alpaca to enable the integration.

Finally, you'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Alpaca processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4  (async function(){
5    var linkHandler = Plaid.create({
6      // Make a request to your server to fetch a new link_token.
7      token: (await $.post('/create_link_token')).link_token,
8      onSuccess: function(public_token, metadata) {
9        // The onSuccess function is called when the user has successfully
10        // authenticated and selected an account to use.
11        //
12        // When called, you will send the public_token and the selected accounts,
13        // metadata.accounts, to your backend app server.
14        sendDataToBackendServer({
15           public_token: public_token,
16           accounts: metadata.accounts
17        });
18      },
19      onExit: function(err, metadata) {
20        // The user exited the Link flow.
21        if (err != null) {
22            // The user encountered a Plaid API error prior to exiting.
23        }
24        // metadata contains information about the institution
25        // that the user selected and the most recent API request IDs.
26        // Storing this information can be helpful for support.
27      },
28    });
29  })();
30
31  // Trigger the authentication view
32  document.getElementById('linkButton').onclick = function() {
33    // Link will automatically detect the institution ID
34    // associated with the public token and present the
35    // credential view to your user.
36    linkHandler.open();
37  };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Alpaca, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Alpaca processor_token. You'll send this token to Alpaca and they will use it to securely retrieve account and routing numbers from Plaid.

You can create Alpaca processor_tokens in all three API environments:

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest } = require('plaid');
2
3// Change sandbox to development to test with live users;
4// Change to production when you're ready to go live!
5const configuration = new Configuration({
6  basePath: PlaidEnvironments[process.env.PLAID_ENV],
7  baseOptions: {
8    headers: {
9      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
10      'PLAID-SECRET': process.env.PLAID_SECRET,
11      'Plaid-Version': '2020-09-14',
12    },
13  },
14});
15
16const plaidClient = new PlaidApi(configuration);
17
18try {
19  // Exchange the public_token from Plaid Link for an access token.
20  const tokenResponse = await plaidClient.itemPublicTokenExchange({
21    public_token: publicToken,
22  });
23  const accessToken = tokenResponse.data.access_token;
24
25  // Create a processor token for a specific account id.
26  const request: ProcessorTokenCreateRequest = {
27    access_token: accessToken,
28    account_id: accountID,
29    processor: 'alpaca',
30  };
31  const processorTokenResponse = await plaidClient.processorTokenCreate(
32    request,
33  );
34  const processorToken = processorTokenResponse.data.processor_token;
35} catch (error) {
36  // handle error
37}

For a valid request, the API will return a JSON response similar to:

1{
2  "processor_token": "processor-sandbox-0asd1-a92nc",
3  "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Example code in Plaid Pattern

For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in items.js

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Alpaca Production credentials prior to initiating live payment transactions in the Alpaca API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

identity add to app

Add Identity to your app

Use Identity to verify user data

In this guide, we'll start from scratch and walk through how to use Identity to retrieve identity data. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, you can skip ahead to Fetching identity data.

Get Plaid API keys and complete application and company profile

If you don't already have one, you'll need to create a Plaid developer account. After creating your account, you can find your API keys under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your application profile and company profile on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the Plaid Portal. Your application profile and company profile must be completed before connecting to certain institutions in Production.

Install and initialize Plaid libraries

You can use our official server-side client libraries to connect to the Plaid API from your application:

Select group for content switcher
Select Language
1// Install via npm
2npm install --save plaid

After you've installed Plaid's client libraries, you can initialize them by passing in your client_id, secret, and the environment you wish to connect to (Sandbox, Development, or Production). This will make sure the client libraries pass along your client_id and secret with each request, and you won't need to explicitly include them in any other calls.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can obtain from the Dashboard. These code samples also demonstrate starting up a server commonly used in each framework (such as Express or Flask).

Select group for content switcher
Select Language
1// Using Express
2const express = require('express');
3const app = express();
4app.use(express.json());
5
6const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
7
8const configuration = new Configuration({
9  basePath: PlaidEnvironments.sandbox,
10  baseOptions: {
11    headers: {
12      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
13      'PLAID-SECRET': process.env.PLAID_SECRET,
14    },
15  },
16});
17
18const client = new PlaidApi(configuration);

Create an Item in Link

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the Link documentation.

Using Link, we will create a Plaid Item, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. If you want to customize Link's look and feel, you can do so from the Dashboard.

Before initializing Link, you will need to create a new link_token on the server side of your application. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the /link/token/create endpoint. Then, on the client side of your application, you'll need to initialize Link with the link_token that you just created.

Create a link_token
Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['identity'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Install Link dependency
Select Language
1<head>
2  <title>Connect a bank</title>
3  <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
4</head>
Configure the client-side Link handler
1const linkHandler = Plaid.create({
2  token: (await $.post('/create_link_token')).link_token,
3  onSuccess: (public_token, metadata) => {
4    // Send the public_token to your app server.
5    $.post('/exchange_public_token', {
6      public_token: public_token,
7    });
8  },
9  onExit: (err, metadata) => {
10    // Optionally capture when your user exited the Link flow.
11    // Storing this information can be helpful for support.
12  },
13  onEvent: (eventName, metadata) => {
14    // Optionally capture Link flow events, streamed through
15    // this callback as your users connect an Item to Plaid.
16  },
17});
18
19linkHandler.open();

Get a persistent access_token

Next, on the server side, we need to exchange our public_token for an access_token and item_id. The access_token will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the /item/public_token/exchange endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the access_token and item_id in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. The access_token will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via /item/remove. The access_token should be stored securely, and never in client-side code. A public_token is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

Select group for content switcher
Select Language
1app.post('/api/exchange_public_token', async function (
2  request,
3  response,
4  next,
5) {
6  const publicToken = request.body.public_token;
7  try {
8    const response = await client.itemPublicTokenExchange({
9      public_token: publicToken,
10    });
11
12    // These values should be saved to a persistent database and
13    // associated with the currently signed-in user
14    const accessToken = response.data.access_token;
15    const itemID = response.data.item_id;
16
17    res.json({ public_token_exchange: 'complete' });
18  } catch (error) {
19    // handle error
20  }
21});

Fetching Identity data

Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API. Once you've retrieved identity data for an account, you can then use it to collect end-user contact information or evaluate whether they may constitute a fraud risk. For more detailed information on the schema returned, see /identity/get.

Select group for content switcher
Select Language
1const { IdentityGetRequest } = require('plaid');
2
3// Pull Identity data for an Item
4const request: IdentityGetRequest = {
5  access_token: accessToken,
6};
7try {
8  const response = await plaidClient.identityGet(request);
9  const identities = response.data.accounts.flatMap(
10    (account) => account.owners,
11  );
12} catch (error) {
13  // handle error
14}

Example response data is below.

1{
2  "accounts": [
3    {
4      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
5      "balances": {
6        "available": 100,
7        "current": 110,
8        "iso_currency_code": "USD",
9        "limit": null,
10        "unofficial_currency_code": null
11      },
12      "mask": "0000",
13      "name": "Plaid Checking",
14      "official_name": "Plaid Gold Standard 0% Interest Checking",
15      "owners": [
16        {
17          "addresses": [
18            {
19              "data": {
20                "city": "Malakoff",
21                "country": "US",
22                "postal_code": "14236",
23                "region": "NY",
24                "street": "2992 Cameron Road"
25              },
26              "primary": true
27            },
28            {
29              "data": {
30                "city": "San Matias",
31                "country": "US",
32                "postal_code": "93405-2255",
33                "region": "CA",
34                "street": "2493 Leisure Lane"
35              },
36              "primary": false
37            }
38          ],
39          "emails": [
40            {
41              "data": "accountholder0@example.com",
42              "primary": true,
43              "type": "primary"
44            },
45            {
46              "data": "accountholder1@example.com",
47              "primary": false,
48              "type": "secondary"
49            }
50          ],
51          "names": ["Alberta Bobbeth Charleson"],
52          "phone_numbers": [
53            {
54              "data": "1112223333",
55              "primary": false,
56              "type": "home"
57            },
58            {
59              "data": "1112224444",
60              "primary": false,
61              "type": "work"
62            },
63            {
64              "data": "1112225555",
65              "primary": false,
66              "type": "mobile1"
67            }
68          ]
69        }
70      ],
71      "subtype": "checking",
72      "type": "depository"
73    }
74  ],
75  "item": {
76    "available_products": ["balance", "credit_details", "investments"],
77    "billed_products": [
78      "assets",
79      "auth",
80      "identity",
81      "liabilities",
82      "transactions"
83    ],
84    "consent_expiration_time": null,
85    "error": null,
86    "institution_id": "ins_3",
87    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
88    "webhook": "https://www.genericwebhookurl.com/webhook"
89  },
90  "request_id": "3nARps6TOYtbACO"
91}

Tutorial and example code in Plaid Pattern

For a real-life example of an app that incorporates Identity, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that fetches Identity data in order verify identity prior to a funds transfer. The Identity code can be found in items.js.

For a tutorial walkthrough of creating a similar app, see Account funding tutorial.

Next steps

If you're ready to launch to Production, see the Launch checklist.

transfer sweeping funds

Sweeping Funds

Learn how Plaid sweeps funds

Overview

A sweep is the automatic transfer of funds covering credit activity, funding of debits, and any returns. There is no Plaid API integration required to sweep funds to your business checking or treasury account. However, if you'd like to understand how transactions received from Plaid in your primary business bank account relate to transfer activity, this article outlines Plaid's sweep process and the endpoints you can use to track sweep status.

Sweep process

After the daily transfer cutoff, Plaid determines the net-sum of all transfers and automatically sweeps the sum to your business checking or treasury account via an ACH credit. The sweep includes credits initiated the day of, debits that have passed their hold, and any ACH returns. Because there are two transfer cutoffs each day, one for same-day transfers and one for next-day transfers, there are two sweep events each day, one for each type of transfer. If you have been informed by your Plaid Account Manager that your transfer account is subject to a mandatory hold time, the hold will take place after the sweep and will not affect sweep schedules.

For example, say your business checking account starts the day with $10,000. Throughout the day, you send out credits totaling $1,000 and collect a total of $3,000 of debits from users. Because credits are swept on the day of initiation, Plaid will sweep -$1,000 at the end of the day to cover the credit activity. On the next day, assuming there is a 1 day hold on debits, Plaid will sweep $3,000 (minus any returns that come in) to your main treasury account, bringing your account total to $12,000. Reach out to your Plaid point of contact if you need to change the business checking or treasury account where you receive these sweeps.

Sweep endpoints

The following endpoints allow you to retrieve detailed information about sweeps and simulate sweeps in the Plaid Sandbox.

These endpoints can help you understand which user payments or disbursements have been sent or withdrawn, as well as how returns affect the total amount delivered each day to your account. You can use these endpoints in combination with the sweep_status field returned by various Transfer endpoints for visibility on when payment instructions are submitted to the network, enabling you to set better expectations with your users around expected funds availability.

In this guide, we'll demonstrate how to use these endpoints to reconcile transactions, track transfers, and simulate sweeps in the Sandbox.

Reconciling transactions

You can use the /transfer/sweep/list endpoint to reconcile transactions received from Plaid against your primary business bank account. For example, consider the following entries in your bank account from Plaid:

EntryAmountDate
PLAID 105778927 CCD-\$5,264.62November 18, 2021
PLAID 207407127 CCD\$2,367.80November 16, 2021
PLAID 5729756 CCD\$6,007.49November 10, 2021

For more information about entries of this nature, use the /transfer/sweep/list endpoint and specify a time frame that encapsulates the entries.

Select Language
1const request: TransferSweepListRequest = {
2  start_date: '2021-11-01T00:00.000Z',
3  end_date: '2021-11-30T00:00.000Z',
4};
5try {
6  const response = await plaidClient.transferSweepList(request);
7  const sweeps = response.data.sweeps;
8  for (const sweep of sweeps) {
9    // iterate through sweeps
10  }
11} catch (error) {
12  // handle error
13}
1{
2  "sweeps": [
3    {
4      "id": "464744e6-911a-43e8-9848-ba531d6dc39a",
5      "amount": "-5264.62",
6      "created": "2021-11-18T07:10.824Z"
7    },
8    {
9      "id": "f7ccab27-95e7-4014-bb20-12f6bb698d51",
10      "amount": "2367.80",
11      "created": "2021-11-16T07:06.854Z"
12    },
13    {
14      "id": "6f91af76-fcb9-4844-9aad-32b115a8ac9a",
15      "amount": "0.00",
16      "created": "2021-11-15T07:04.859Z"
17    },
18    {
19      "id": "4576eeca-9aaf-4db9-9857-801f44f558a9",
20      "amount": "6007.49",
21      "created": "2021-11-10T07:07.854Z"
22    }
23  ],
24  "request_id": "saKrIBuEB9qJZno"
25}

Each sweep object in the sweeps list can be matched to entries in your business account ledger by iterating through them chronologically. Confirm that the amount in each sweep object matches the amount of the corresponding line item in your ledger.

In addition, note that the created field in a sweep object represents the sweep origination time, which is typically 1 business bank day prior to the date shown for the corresponding entry in your ledger. In certain cases, however, the sweep origination time may be up to 4 days prior to the date shown for the corresponding entry in your ledger. This can happen if a sweep is initiated on a day prior to a long weekend (e.g., for a sweep initiated on a Friday before a 3 day weekend, the ledger entry would appear 4 days later, on Tuesday).

Net-settlement of funds can occur without executing a corresponding sweep to your bank account. This can happen if the net amount of credits and debits originated on the same day are equal. If this occurs, Plaid will create a sweep with a value of "0.00" for the amount field. Sweep objects with a value of "0.00" will not have a corresponding entry in your ledger.

After reconciling a sweep with a line item in your ledger, you can use the /transfer/event/list endpoint to determine which transfers were included in the sweep.

Select Language
1const request: TransferEventListRequest = {
2  sweep_id: '3bbc5c99-05aa-4f6c-b618-c0f881e3745f',
3};
4try {
5  const response = await plaidClient.transferEventList(request);
6  const events = response.data.transfer_events;
7  for (const event of events) {
8    // iterate through events
9  }
10} catch (error) {
11  // handle error
12}
1{
2  "transfer_events": [
3    {
4      "account_id": "AgbZBPQPWwT15dZnyEzLs1dLWlK4XrF1awz1m",
5      "event_id": "1002",
6      "event_type": "swept",
7      "sweep_amount": "5.00",
8      "sweep_id": "3bbc5c99-05aa-4f6c-b618-c0f881e3745f",
9      "timestamp": "2021-11-18T02:25.436Z",
10      "transfer_amount": "5.00",
11      "transfer_id": "a574f217-6963-49d3-84f3-c3b83975ced5",
12      "transfer_type": "debit"
13    },
14    {
15      "account_id": "vQJblmka1Vt5pabdlZnmHwG4RpV5VMhWlLrXm",
16      "event_id": "1001",
17      "event_type": "return_swept",
18      "sweep_amount": "-2348.00",
19      "sweep_id": "3bbc5c99-05aa-4f6c-b618-c0f881e3745f",
20      "timestamp": "2021-11-18T02:25.436Z",
21      "transfer_amount": "2348.00",
22      "transfer_id": "945bcfaf-3047-4b98-b4f6-f96dfa63fae2",
23      "transfer_type": "debit"
24    },
25    {
26      "account_id": "pN7xbQ4eejcwkBzlNnRlFyo5o5zMapILXrL1Q",
27      "event_id": "1000",
28      "event_type": "swept",
29      "sweep_amount": "-62.00",
30      "sweep_id": "3bbc5c99-05aa-4f6c-b618-c0f881e3745f",
31      "timestamp": "2021-11-18T02:25.436Z",
32      "transfer_amount": "62.00",
33      "transfer_id": "fde3ba0e-6ae7-4dc2-8309-b7348161a1d6",
34      "transfer_type": "credit"
35    }
36  ],
37  "request_id": "saKrIBuEB9qJZno"
38}

Each object in the transfer_events list corresponds to a transfer in the sweep and includes information about the transfer type, event type, and sweep amount. The following table explains how the sign of an amount is determined.

transfer_typeevent_typesweep_amount (positive or negative)
debitswept+ (funds deposited to your account)
debitreturn_swept- (funds withdrawn from your account)
creditswept- (funds withdrawn from your account)
creditreturn_swept+ (funds deposited to your account)

Transfer states and events

Possible transfer states and events
Possible transfer states and events

The diagram above illustrates the possible states and events of a transfer. The word inside each box represents a transfer's status, while the word below the box represents a transfer's sweep status. The arrows indicate the types of events received via the events API as transfers transition between states.

Intermediate states occur when funds are in the process of being moved. These states occur when there is a funds hold or when different payment rails are used for sweeps and transfers. As an example, Plaid may execute sweeps over standard ACH for a same-day transfer.

If an ACH transaction that has posted is returned, the status of the transfer is updated to returned. If this return occurs before the transfer is swept, the transfer sweep status will remain as unswept. However, if the transfer has already been included in a sweep (i.e., sweep status is swept), Plaid will reverse the sweep and include it in a future sweep (i.e., sweep status updated to return_swept).

Tracking a transfer's lifecycle

When a debit is issued using Transfer, funds are transferred out of the end user's account and held by Plaid before being released to your bank account. During this period, you may inform end users that they can expect to see a debit to their account but that the transfer is still incomplete. Let’s walk through how Plaid creates sweep events and updates a debit status.

When a transfer is created (on day 0), its status is set to "pending" and its sweep status is set to "unswept".

Select Language
1const request: TransferCreateRequest = {
2  type: 'debit',
3  amount: '12.73',
4  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
5};
6try {
7  const response = await client.transferCreate(request);
8  const transfer = response.data.transfer;
9} catch (error) {
10  // handle error
11}
1{
2  "transfer": {
3    "id": "b84020f0-8765-43a4-96b2-828ca387993a",
4    "created": "2021-12-01T16:42:58.028Z",
5    "status": "pending",
6    "sweep_status": "unswept",
7    ...
8  }
9}

At the end of the day (day 0), Plaid submits an ACH transaction to the payment network debiting the user's account. Plaid then creates a "posted" event for the debit and updates the transfer status to "posted".

By the next day (day 1), the end user's financial institution has received the payment instruction from the network and the user can expect to see a debit to their account.

Select Language
1const request: TransferGetRequest = {
2  transfer_id: 'b84020f0-8765-43a4-96b2-828ca387993a',
3};
4try {
5  const response = await plaidClient.transferGet(request);
6  const transfer = response.data.transfer;
7} catch (error) {
8  // handle error
9}
1{
2  "transfer": {
3    "id": "b84020f0-8765-43a4-96b2-828ca387993a",
4    "created": "2021-12-01T16:42:58.028Z",
5    "status": "posted",
6    "sweep_status": "unswept",
7    ...
8  }
9}

The following day (day 2), if the transfer has not been returned, Plaid will sweep the funds to your primary business bank account. Specifically, Plaid creates a sweep for the transfer, emits a "swept" event, and updates the transfer’s sweep status to "swept".

Select Language
1const request: TransferGetRequest = {
2  transfer_id: 'b84020f0-8765-43a4-96b2-828ca387993a',
3};
4try {
5  const response = await plaidClient.transferGet(request);
6  const transfer = response.data.transfer;
7} catch (error) {
8  // handle error
9}
1{
2  "transfer": {
3    "id": "b84020f0-8765-43a4-96b2-828ca387993a",
4    "created": "2021-12-01T16:42:58.028Z",
5    "status": "posted",
6    "sweep_status": "swept",
7    ...
8  }
9}

You can verify the sweep with the /transfer/sweep/list endpoint.

Select Language
1const request: TransferSweepListRequest = {
2  start_date: '2021-11-06T22:35:49Z',
3  end_date: '2021-12-23T22:35:49Z',
4  count: 20,
5};
6try {
7  const response = await plaidClient.transferSweepList(request);
8  const sweeps = response.data.sweeps;
9  for (const sweep of sweeps) {
10    // iterate through sweeps
11  }
12} catch (error) {
13  // handle error
14}
1{
2  "sweeps": [
3    {
4    "id": "b84020f0-8765-43a4-96b2-828ca387993a",
5    "amount": "12.73",
6    "created": "2021-12-04T04:30:58.028Z",
7    ...
8    },
9    ...
10  ]
11}

Simulating sweeps in Sandbox

You can use the /sandbox/transfer/sweep/simulate endpoint to simulate sweeps in the Plaid Sandbox. For example, consider the following response from /transfer/list.

1{
2  "transfers": [
3    {
4      "id": "00000000-8965-48f9-8b1a-5948b366a77d",
5      "type": "debit",
6      "amount": "5.75",
7      "status": "posted",
8      "sweep_status": "unswept",
9      ...
10    },
11    {
12      "id": "11111111-aa2f-4735-a00f-f4e0d2d2faee",
13      "type": "debit",
14      "amount": "10.00",
15      "status": "posted",
16      "sweep_status": "unswept",
17      ...
18    }
19  ]
20}

To simulate a sweep for these transfers in the Sandbox, call the /sandbox/transfer/sweep/simulate endpoint.

Select Language
1const request: SandboxTransferSweepSimulateRequest = {
2  client_id,
3  secret,
4};
5try {
6  const response = await plaidClient.sandboxTransferSweepSimulate(request);
7  const sweep = response.data.sweep;
8} catch (error) {
9  // handle error
10}

The response is a sweep object with additional information about the sweep, including the total amount resulting from the sweep event.

1{
2  "sweep": {
3    "id": "d5394a4d-0b04-4a02-9f4a-7ca5c0f52f9d",
4    "created_at": "2020-12-03T07:27:15Z",
5    "amount": "15.75",
6    "iso_currency_code": "USD"
7  },
8  "request_id": "mdqfuVxeoza6mhu"
9}

You can then view the transfer events created for the sweep.

Select Language
1const request: TransferEventListRequest = {
2  sweep_id: 'd5394a4d-0b04-4a02-9f4a-7ca5c0f52f9d',
3};
4try {
5  const response = await plaidClient.transferEventList(request);
6  const events = response.data.transfer_events;
7  for (const event of events) {
8    // iterate through events
9  }
10} catch (error) {
11  // handle error
12}
1{
2  "transfer_events": [
3    {
4      "account_id": "dVvzoDmL77sl8mJlmlDri93QvomVRoTZklEyd",
5      "event_id": 101,
6      "event_type": "swept",
7      "sweep_amount": "5.75",
8      "sweep_id": "d5394a4d-0b04-4a02-9f4a-7ca5c0f52f9d",
9      "timestamp": "2021-12-03T15:09:14.431Z",
10      "transfer_amount": "5.75",
11      "transfer_id": "00000000-8965-48f9-8b1a-5948b366a77d",
12      "transfer_type": "debit"
13    },
14    {
15      "account_id": "dVvzoDmL77sl8mJlmlDri93QvomVRoTZklEyd",
16      "event_id": 100,
17      "event_type": "swept",
18      "sweep_amount": "10.00",
19      "sweep_id": "d5394a4d-0b04-4a02-9f4a-7ca5c0f52f9d",
20      "timestamp": "2021-12-03T15:09:14.431Z",
21      "transfer_amount": "10.00",
22      "transfer_id": "11111111-aa2f-4735-a00f-f4e0d2d2faee",
23      "transfer_type": "debit"
24    }
25  ]
26}

You can also simulate returns and return sweeps. Start by simulating a return using /sandbox/transfer/simulate. In the following example, we'll simulate a return of the \$10 debit (transfer_id of 11111111-aa2f-4735-a00f-f4e0d2d2faee).

Select Language
1const request: SandboxTransferSimulateRequest = {
2  transfer_id: '11111111-aa2f-4735-a00f-f4e0d2d2faee',
3  event_type: 'returned',
4};
5try {
6  const response = await plaidClient.sandboxTransferSimulate(request);
7  // empty response upon success
8} catch (error) {
9  // handle error
10}

Next, simulate another sweep using /sandbox/transfer/sweep/simulate.

Select Language
1const request: SandboxTransferSweepSimulateRequest = {
2  client_id,
3  secret,
4};
5try {
6  const response = await plaidClient.sandboxTransferSweepSimulate(request);
7  const sweep = response.data.sweep;
8} catch (error) {
9  // handle error
10}
1{
2  "sweep": {
3    "id": "11111111-293a-4b67-9c3e-35152d752f1c",
4    "created_at": "2021-12-03T17:27:15Z",
5    "amount": "-10.00"
6  },
7  "request_id": "sdqfuPxeopa6mhu"
8}

You can then view the transfer events by calling /transfer/event/list.

Select Language
1const request: TransferEventListRequest = {
2  sweep_id: '11111111-293a-4b67-9c3e-35152d752f1c',
3};
4try {
5  const response = await plaidClient.transferEventList(request);
6  const events = response.data.transfer_events;
7  for (const event of events) {
8    // iterate through events
9  }
10} catch (error) {
11  // handle error
12}
1{
2  "transfer_events": [
3    {
4      "account_id": "dVvzoDmL77sl8mJlmlDri93QvomVRoTZklEyd",
5      "event_id": 102,
6      "event_type": "return_swept",
7      "sweep_amount": "-10.00",
8      "sweep_id": "11111111-293a-4b67-9c3e-35152d752f1c",
9      "timestamp": "2021-12-03T15:09:14.431Z",
10      "transfer_amount": "10.00",
11      "transfer_id": "11111111-aa2f-4735-a00f-f4e0d2d2faee",
12      "transfer_type": "debit"
13    }
14  ]
15}

To view the final sweep statuses for each transfer, call the /transfer/list endpoint and specify a time frame that encapsulates the entries.

1{
2  "transfers": [
3    {
4      "id": "00000000-8965-48f9-8b1a-5948b366a77d",
5      "type": "debit",
6      "amount": "5.75",
7      "status": "posted",
8      "sweep_status": "swept",
9      ...
10    },
11    {
12      "id": "11111111-aa2f-4735-a00f-f4e0d2d2faee",
13      "type": "debit",
14      "amount": "10.00",
15      "status": "returned",
16      "sweep_status": "return_swept",
17      ...
18    }
19  ]
20}

Sample app code

For a real-life example of an app that incorporates the transfer sweep and sandbox simulation endpoints, see the Node-based Plaid Pattern Transfer sample app. Pattern Transfer is a sample subscriptions payment app that enables ACH bank transfers. The Transfer sweep and event simulation code can be found in transfers.js

errors institution

Institution Errors

Guide to troubleshooting Institution errors

INSTITUTION_DOWN

The financial institution is down, either for maintenance or due to an infrastructure issue with their systems.
Sample user-facing error message
Please try connecting a different account: There was a problem processing your request. Your account could not be connected at this time
Link user experience

Your user will be redirected to the Institution Select pane to retry connecting their Item or a different account.

Common causes
  • The institution is undergoing scheduled maintenance.
  • The institution is experiencing temporary technical problems.
Troubleshooting steps

If the error persists, please submit a 'Persistent HTTP 500 errors' Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

1http code 400
2{
3 "error_type": "INSTITUTION_ERROR",
4 "error_code": "INSTITUTION_DOWN",
5 "error_message": "this institution is not currently responding to this request. please try again soon",
6 "display_message": "This financial institution is not currently responding to requests. We apologize for the inconvenience.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INSTITUTION_NOT_ENABLED_IN_ENVIRONMENT

Institution not enabled in this environment
Common causes

You're referencing an Institution that exists, but is not enabled for this environment (e.g calling a Sandbox endpoint with the ID of an Institution that is not enabled there).

1http code 400
2{
3 "error_type": "INSTITUTION_ERROR",
4 "error_code": "INSTITUTION_NOT_ENABLED_IN_ENVIRONMENT",
5 "error_message": "Institution not enabled in this environment",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INSTITUTION_NOT_FOUND

This institution was not found. Please check the ID supplied
Common causes

A call was made using an institution_id that does not exist.

Troubleshooting steps
1http code 400
2{
3 "error_type": "INSTITUTION_ERROR",
4 "error_code": "INSTITUTION_NOT_FOUND",
5 "error_message": "this institution was not found. Please check the ID supplied",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INSTITUTION_NOT_RESPONDING

The financial institution is failing to respond to some of our requests. Your user may be successful if they retry another time.
Sample user-facing error message
Couldn't connect to your institution: If you need to use this app immediately, we recommend trying another institution. Errors like this are usually resolved quickly, so you may want to try the same account again later.
Link user experience

Your user will be redirected to the Institution Select pane to retry connecting their Item or a different account.

Common causes
  • The institution is experiencing temporary technical problems.
Troubleshooting steps

If the error persists, please submit a 'Persistent HTTP 500 errors' Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

1http code 400
2{
3 "error_type": "INSTITUTION_ERROR",
4 "error_code": "INSTITUTION_NOT_RESPONDING",
5 "error_message": "this institution is not currently responding to this request. please try again soon",
6 "display_message": "This financial institution is not currently responding to requests. We apologize for the inconvenience.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INSTITUTION_NOT_AVAILABLE

The financial institution is not available this time.
Link user experience

Your user will be redirected to the Institution Select pane to retry connecting their Item or a different account.

Common causes
  • Plaid’s connection to an institution is temporarily down for maintenance or other planned circumstances.
Troubleshooting steps

If the error persists, please submit a 'Persistent HTTP 500 errors' Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

1http code 400
2{
3 "error_type": "INSTITUTION_ERROR",
4 "error_code": "INSTITUTION_NOT_AVAILABLE",
5 "error_message": "this institution is not currently responding to this request. please try again soon",
6 "display_message": "This financial institution is not currently responding to requests. We apologize for the inconvenience.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INSTITUTION_NO_LONGER_SUPPORTED

Plaid no longer supports this financial institution.
Sample user-facing error message
Please try connecting a different account: There was a problem processing your request. Your account could not be connected at this time.
Common causes
  • The financial institution is no longer supported on Plaid's platform.
  • The institution has switched from supporting non-OAuth-based connections to requiring OAuth-based connections.
1http code 400
2{
3 "error_type": "INSTITUTION_ERROR",
4 "error_code": "INSTITUTION_NO_LONGER_SUPPORTED",
5 "error_message": "this institution is no longer supported",
6 "display_message": "This financial institution is no longer supported. We apologize for the inconvenience.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

UNAUTHORIZED_INSTITUTION

You are not authorized to create Items for this institution at this time.
Common causes
  • Access to this institution is subject to additional verification and must be manually enabled for your account.
  • You have not yet completed the OAuth registration requirements for the institution.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INSTITUTION_ERROR",
4 "error_code": "UNAUTHORIZED_INSTITUTION",
5 "error_message": "not authorized to create items for this institution",
6 "display_message": "You are not authorized to create items for this institution at this time.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INSTITUTION_REGISTRATION_REQUIRED

Your application is not yet registered with the institution.
Common causes
  • Details about your application must be registered with this institution before use.
  • If your account has not yet been enabled for Production access, some institutions that require registration may not be available to you.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INSTITUTION_ERROR",
4 "error_code": "INSTITUTION_REGISTRATION_REQUIRED",
5 "error_message": "not yet registered to create items for this institution",
6 "display_message": "You must register your application with this institution before you can create items for it.",
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

assets add to app

Create an Asset Report

Learn how to create Asset Reports with the Assets product

In this guide, we'll start from scratch and walk through how to use Assets to generate and retrieve Asset Reports. If a user's Asset Report involves data from multiple financial institutions, the user will need to allow access to each institution, which will in turn enable you to access their data from each institution. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, you can skip ahead to Creating Asset Reports.

Get Plaid API keys and complete application and company profile

If you don't already have one, you'll need to create a Plaid developer account. After creating your account, you can find your API keys under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your application profile and company profile in the Dashboard. This will provide basic information about your app to help users manage their connection on the Plaid Portal at my.plaid.com. The application profile and company profile must be completed before connecting to certain institutions in Production.

Install and initialize Plaid libraries

You can use our official server-side client libraries to connect to the Plaid API from your application:

Select group for content switcher
Select Language
1// Install via npm
2npm install --save plaid

After you've installed Plaid's client libraries, you can initialize them by passing in your client_id, secret, and the environment you wish to connect to (Sandbox, Development, or Production). This will make sure the client libraries pass along your client_id and secret with each request, and you won't need to explicitly include it in any other calls.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can obtain from the Dashboard. These code samples also demonstrate starting up a server commonly used in each framework (such as Express or Flask).

Select group for content switcher
Select Language
1// Using Express
2const express = require('express');
3const app = express();
4app.use(express.json());
5
6const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
7
8const configuration = new Configuration({
9  basePath: PlaidEnvironments.sandbox,
10  baseOptions: {
11    headers: {
12      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
13      'PLAID-SECRET': process.env.PLAID_SECRET,
14    },
15  },
16});
17
18const client = new PlaidApi(configuration);

Create an Item in Link

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the Link documentation.

Using Link, we will create a Plaid Item, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. Asset Reports can consist of user data from multiple financial institutions; users will need to use Link to provide access to each financial institution, providing you with multiple Items. If you want to customize Link's look and feel, you can do so from the Dashboard.

Before initializing Link, you will need to create a new link_token on the server side of your application. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the /link/token/create endpoint. Then, on the client side of your application, you'll need to initialize Link with the link_token that you just created. Since, for Assets, users may need to grant access to more than one financial institution via Link, you may need to initialize Link more than once.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can obtain from the Dashboard.

Create a link_token
Select group for content switcher
Select Language
1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['assets'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});
Install Link dependency
Select Language
1<head>
2  <title>Connect a bank</title>
3  <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
4</head>
Configure the client-side Link handler
1const linkHandler = Plaid.create({
2  token: (await $.post('/create_link_token')).link_token,
3  onSuccess: (public_token, metadata) => {
4    // Send the public_token to your app server.
5    $.post('/exchange_public_token', {
6      public_token: public_token,
7    });
8  },
9  onExit: (err, metadata) => {
10    // Optionally capture when your user exited the Link flow.
11    // Storing this information can be helpful for support.
12  },
13  onEvent: (eventName, metadata) => {
14    // Optionally capture Link flow events, streamed through
15    // this callback as your users connect an Item to Plaid.
16  },
17});
18
19linkHandler.open();

Get a persistent access_token

Next, on the server side, we need to exchange our public_token for an access_token and item_id for each Item the user provided you with via Link. The access_token will allow us to make authenticated calls to the Plaid API for its corresponding financial institution. Doing so is as easy as calling the /item/public_token/exchange endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the access_tokens and item_ids in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. An access_token will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via /item/remove. An access_token should be stored securely and never in client-side code. A public_token is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

Select group for content switcher
Select Language
1app.post('/api/exchange_public_token', async function (
2  request,
3  response,
4  next,
5) {
6  const publicToken = request.body.public_token;
7  try {
8    const response = await client.itemPublicTokenExchange({
9      public_token: publicToken,
10    });
11
12    // These values should be saved to a persistent database and
13    // associated with the currently signed-in user
14    const accessToken = response.data.access_token;
15    const itemID = response.data.item_id;
16
17    res.json({ public_token_exchange: 'complete' });
18  } catch (error) {
19    // handle error
20  }
21});

Creating Asset Reports

Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API and create an Asset Report using the /asset_report/create endpoint.

Assets sample request: create
Select group for content switcher
Select Language
1const { AssetReportCreateRequest } = require('plaid');
2
3const daysRequested = 60;
4const options = {
5  client_report_id: '123',
6  webhook: 'https://www.example.com',
7  user: {
8    client_user_id: '789',
9    first_name: 'Jane',
10    middle_name: 'Leah',
11    last_name: 'Doe',
12    ssn: '123-45-6789',
13    phone_number: '(555) 123-4567',
14    email: 'jane.doe@example.com',
15  },
16};
17const request: AssetReportCreateRequest = {
18  access_tokens: [accessToken],
19  days_requested,
20  options,
21};
22// accessTokens is an array of Item access tokens.
23// Note that the assets product must be enabled for all Items.
24// All fields on the options object are optional.
25try {
26  const response = await plaidClient.assetReportCreate(request);
27  const assetReportId = response.data.asset_report_id;
28  const assetReportToken = response.data.asset_report_token;
29} catch (error) {
30  // handle error
31}

Sample response data is below.

1{
2  "asset_report_token": "assets-sandbox-6f12f5bb-22dd-4855-b918-f47ec439198a",
3  "asset_report_id": "1f414183-220c-44f5-b0c8-bc0e6d4053bb",
4  "request_id": "Iam3b"
5}

Fetching asset data

Once an Asset Report has been created, it can be retrieved to analyze the user's loan eligibility. For more detailed information on the schema for Asset Reports, see /asset_report/get.

Asset Reports are not generated instantly. If you receive a PRODUCT_NOT_READY error when calling /asset_report/get, the requested Asset Report has not yet been generated. To be alerted when the requested Asset Report has been generated, listen to Assets webhooks.

Assets sample request: get
Select group for content switcher
Select Language
1const { AssetReportGetRequest } = require('plaid');
2
3const request: AssetReportGetRequest = {
4  asset_report_token: assetReportToken,
5  include_insights: true,
6};
7try {
8  const response = await plaidClient.assetReportGet(request);
9  const assetReportId = response.data.asset_report_id;
10} catch (error) {
11  // handle error
12}

Sample response data is below.

1{
2  "report": {
3    "asset_report_id": "bf3a0490-344c-4620-a219-2693162e4b1d",
4    "client_report_id": "123abc",
5    "date_generated": "2020-06-05T22:47:53Z",
6    "days_requested": 2,
7    "items": [
8      {
9        "accounts": [
10          {
11            "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
12            "balances": {
13              "available": 200,
14              "current": 210,
15              "iso_currency_code": "USD",
16              "limit": null,
17              "unofficial_currency_code": null
18            },
19            "days_available": 2,
20            "historical_balances": [
21              {
22                "current": 210,
23                "date": "2020-06-04",
24                "iso_currency_code": "USD",
25                "unofficial_currency_code": null
26              },
27              {
28                "current": 210,
29                "date": "2020-06-03",
30                "iso_currency_code": "USD",
31                "unofficial_currency_code": null
32              }
33            ],
34            "mask": "1111",
35            "name": "Plaid Saving",
36            "official_name": "Plaid Silver Standard 0.1% Interest Saving",
37            "owners": [
38              {
39                "addresses": [
40                  {
41                    "data": {
42                      "city": "Malakoff",
43                      "country": "US",
44                      "postal_code": "14236",
45                      "region": "NY",
46                      "street": "2992 Cameron Road"
47                    },
48                    "primary": true
49                  },
50                  {
51                    "data": {
52                      "city": "San Matias",
53                      "country": "US",
54                      "postal_code": "93405-2255",
55                      "region": "CA",
56                      "street": "2493 Leisure Lane"
57                    },
58                    "primary": false
59                  }
60                ],
61                "emails": [
62                  {
63                    "data": "accountholder0@example.com",
64                    "primary": true,
65                    "type": "primary"
66                  },
67                  {
68                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
69                    "primary": false,
70                    "type": "other"
71                  }
72                ],
73                "names": ["Alberta Bobbeth Charleson"],
74                "phone_numbers": [
75                  {
76                    "data": "1112223333",
77                    "primary": false,
78                    "type": "home"
79                  },
80                  {
81                    "data": "1112225555",
82                    "primary": false,
83                    "type": "mobile1"
84                  }
85                ]
86              }
87            ],
88            "ownership_type": null,
89            "subtype": "savings",
90            "transactions": [],
91            "type": "depository"
92          },
93          {
94            "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
95            "balances": {
96              "available": null,
97              "current": 56302.06,
98              "iso_currency_code": "USD",
99              "limit": null,
100              "unofficial_currency_code": null
101            },
102            "days_available": 2,
103            "historical_balances": [],
104            "mask": "8888",
105            "name": "Plaid Mortgage",
106            "official_name": null,
107            "owners": [
108              {
109                "addresses": [
110                  {
111                    "data": {
112                      "city": "Malakoff",
113                      "country": "US",
114                      "postal_code": "14236",
115                      "region": "NY",
116                      "street": "2992 Cameron Road"
117                    },
118                    "primary": true
119                  },
120                  {
121                    "data": {
122                      "city": "San Matias",
123                      "country": "US",
124                      "postal_code": "93405-2255",
125                      "region": "CA",
126                      "street": "2493 Leisure Lane"
127                    },
128                    "primary": false
129                  }
130                ],
131                "emails": [
132                  {
133                    "data": "accountholder0@example.com",
134                    "primary": true,
135                    "type": "primary"
136                  },
137                  {
138                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
139                    "primary": false,
140                    "type": "other"
141                  }
142                ],
143                "names": ["Alberta Bobbeth Charleson"],
144                "phone_numbers": [
145                  {
146                    "data": "1112223333",
147                    "primary": false,
148                    "type": "home"
149                  },
150                  {
151                    "data": "1112225555",
152                    "primary": false,
153                    "type": "mobile1"
154                  }
155                ]
156              }
157            ],
158            "ownership_type": null,
159            "subtype": "mortgage",
160            "transactions": [],
161            "type": "loan"
162          },
163          {
164            "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
165            "balances": {
166              "available": null,
167              "current": 410,
168              "iso_currency_code": "USD",
169              "limit": null,
170              "unofficial_currency_code": null
171            },
172            "days_available": 2,
173            "historical_balances": [
174              {
175                "current": 410,
176                "date": "2020-06-04",
177                "iso_currency_code": "USD",
178                "unofficial_currency_code": null
179              },
180              {
181                "current": 410,
182                "date": "2020-06-03",
183                "iso_currency_code": "USD",
184                "unofficial_currency_code": null
185              }
186            ],
187            "mask": "3333",
188            "name": "Plaid Credit Card",
189            "official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
190            "owners": [
191              {
192                "addresses": [
193                  {
194                    "data": {
195                      "city": "Malakoff",
196                      "country": "US",
197                      "postal_code": "14236",
198                      "region": "NY",
199                      "street": "2992 Cameron Road"
200                    },
201                    "primary": true
202                  },
203                  {
204                    "data": {
205                      "city": "San Matias",
206                      "country": "US",
207                      "postal_code": "93405-2255",
208                      "region": "CA",
209                      "street": "2493 Leisure Lane"
210                    },
211                    "primary": false
212                  }
213                ],
214                "emails": [
215                  {
216                    "data": "accountholder0@example.com",
217                    "primary": true,
218                    "type": "primary"
219                  },
220                  {
221                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
222                    "primary": false,
223                    "type": "other"
224                  }
225                ],
226                "names": ["Alberta Bobbeth Charleson"],
227                "phone_numbers": [
228                  {
229                    "data": "1112223333",
230                    "primary": false,
231                    "type": "home"
232                  },
233                  {
234                    "data": "1112225555",
235                    "primary": false,
236                    "type": "mobile1"
237                  }
238                ]
239              }
240            ],
241            "ownership_type": null,
242            "subtype": "credit card",
243            "transactions": [],
244            "type": "credit"
245          }
246        ],
247        "date_last_updated": "2020-06-05T22:47:52Z",
248        "institution_id": "ins_3",
249        "institution_name": "Chase",
250        "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6"
251      }
252    ],
253    "user": {
254      "client_user_id": "123456789",
255      "email": "accountholder0@example.com",
256      "first_name": "Alberta",
257      "last_name": "Charleson",
258      "middle_name": "Bobbeth",
259      "phone_number": "111-222-3333",
260      "ssn": "123-45-6789"
261    }
262  },
263  "request_id": "eYupqX1mZkEuQRx",
264  "warnings": []
265}

Working with Assets data

After your initial /asset_report/create and /asset_report/get requests, you may want your application to fetch updated Asset Reports, provide Audit Copies of Asset Reports, and more. Consult the API Reference to explore these and other options.

Next steps

If you're ready to launch to Production, see the Launch checklist.

api versioning

API versioning and changelog

Keep track of changes and updates to the Plaid API

API versioning

This page covers backwards-incompatible, versioned API changes. For a list of all API updates, including non-versioned ones, see the changelog.

Whenever we make a backwards-incompatible change to a general availability, non-beta product, we release a new API version to avoid causing breakages for existing developers. You can then continue to use the old API version, or update your application to upgrade to the new Plaid API version. APIs for beta products are subject to breaking changes without versioning, with 30 days notice.

We consider the following changes to be backwards compatible:

  • Adding new API endpoints
  • Adding new optional parameters to existing endpoints
  • Adding new data elements to existing response schemas or webhooks
  • Adding new enum values, including error_types and error_codes
  • Subdividing existing error_codes into more precise errors, and changing the http response code as necessary, as long as the error cannot be resolved via developer action (such as retries) during runtime. For example, changing PRODUCT_NOT_READY errors to a different error_code would be a breaking change, since that error can be resolved by retrying later, but converting an existing INTERNAL_SERVER_ERROR to a more specific error would not be.
  • Adding new webhook_types and webhook_codes
  • Changing the length or content of any API identifier
How to set your API version

The default version of the API used in any requests you make can be configured in the Dashboard and will be used when version information is not otherwise specified. You can also manually set the Plaid-Version header to use a specific version for a given API request.

If you're using one of the Plaid client libraries, they should all be pinned to the latest version of the API at the time when they were released. This means that you can change the API version you're using by updating to a newer version of the client library.

Select group for content switcher
Select Language
1const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
2
3const configuration = new Configuration({
4  basePath: PlaidEnvironments[process.env.PLAID_ENV],
5  baseOptions: {
6    headers: {
7      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
8      'PLAID-SECRET': process.env.PLAID_SECRET,
9      'Plaid-Version': '2020-09-14',
10    },
11  },
12});
13
14const client = new PlaidApi(configuration);

Version 2020-09-14

This version includes several changes to improve authentication, streamline and simplify the API, and improve international support.

  • To improve authentication, the public_key has been fully removed from the API. Endpoints that previously accepted a public_key for authentication, namely /institutions/get_by_id and /institutions/search, now require a client_id and secret for authentication instead.

  • /item/remove no longer returns a removed boolean. This field created developer confusion, because it was never possible for it to return false. A failed /item/remove call will result in an error being returned instead.

  • Several undocumented and unused fields have been removed from the institution object returned by the institutions endpoints /institutions/get, /institutions/get_by_id, and /institutions/search. The removed fields are: input_spec, credentials, include_display_data, has_mfa, mfa, and mfa_code_type.

  • The institutions endpoints /institutions/get, /institutions/get_by_id, and /institutions/search now require the use of a country_codes parameter and no longer use US as a default value if country_codes is not specified, as this behavior caused confusion and unexpected behavior for non-US developers. As part of this change, the country_codes parameter has been moved out of the options object and is now a top-level parameter.

  • To support international payments, the response schema for the partner-only /processor/auth/get endpoint has changed. The 2018-05-22 and 2019-05-29 API releases previously extended the response schema for /auth/get in order to support international accounts, but these changes were never extended to the /processor/auth/get endpoint. This release brings the response for /processor/auth/get in line with the /auth/get response, allowing Plaid partners to extend support for using non-ACH payment methods, such as EFT payments (Canada) or SEPA credit and direct debit (Europe). Accommodating this change does not require any code changes from Plaid developers who use partnership integrations, only from the Plaid partners themselves.

1"numbers": [{
2  "account": "9900009606",
3  "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
4  "routing": "011401533",
5  "wire_routing": "021000021"
6}]
1"numbers": {
2  "ach": [{
3    "account": "9900009606",
4    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
5    "routing": "011401533",
6    "wire_routing": "021000021"
7  }],
8  "eft":[{
9    "account": "111122223333",
10    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
11    "institution": "021",
12    "branch": "01140"
13  }],
14  "international":[{
15    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
16    "bic": "NWBKGB21"
17    "iban": "GB29NWBK60161331926819",
18  }],
19  "bacs":[{
20    "account": "31926819",
21    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
22    "sort_code": "601613"
23  }]
24}

Version 2019-05-29

  • The Auth numbers schema has been extended to support BACS (UK) and other international (IBAN and BIC) account numbers used across the EU.
  • Renamed the zip field to postal_code and the state field to region in all Identity and Transactions responses to be more international friendly.
  • Identity objects in Identity responses are now embedded on the owners field of the corresponding account.
  • Address data fields for Identity responses are now nullable and are returned with a null value when they aren’t available rather than an empty string.
  • Added a ISO-3166-1 alpha-2 country field to all Identity and Transactions responses.
  • The account type brokerage has been renamed to investment.

These changes are meant to enable access to International institutions for Plaid’s launch in Europe and add support for investment accounts. Test in the Sandbox with the new API version to see the new Schema and enable support for International institutions from the Dashboard in order to create Items for these institutions.

Auth

Before, numbers only had fields for ach (US accounts) and eft (Canadian accounts) accounts numbers:

1"numbers": {
2  "ach": [{
3    "account": "9900009606",
4    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
5    "routing": "011401533",
6    "wire_routing": "021000021"
7  }],
8  "eft":[{
9    "account": "111122223333",
10    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
11    "institution": "021",
12    "branch": "01140"
13  }]
14}

Now, the structure of numbers hasn’t changed, but it can have ach, eft, bacs (UK accounts), or international (currently EU accounts) numbers. Note that the schema for each of these numbers are different from one another. It is possible for multiple networks to be present in the response.

1"numbers": {
2  "ach": [{
3    "account": "9900009606",
4    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
5    "routing": "011401533",
6    "wire_routing": "021000021"
7  }],
8  "eft":[{
9    "account": "111122223333",
10    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
11    "institution": "021",
12    "branch": "01140"
13  }],
14  "international":[{
15    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
16    "bic": "NWBKGB21"
17    "iban": "GB29NWBK60161331926819",
18  }],
19  "bacs":[{
20    "account": "31926819",
21    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
22    "sort_code": "601613"
23  }]
24}
Identity

The previous version of Identity had US specific field names and did not include a country as part of the location. Furthermore, the identity data was not scoped to a specific account.

1"identity": {
2  "addresses": [{
3    "accounts": [
4      "Plaid Checking 0000",
5      "Plaid Saving 1111",
6      "Plaid CD 2222"
7    ],
8    "data": {
9      "city": "Malakoff",
10      "state": "NY",
11      "street": "2992 Cameron Road",
12      "zip": "14236"
13    },
14    "primary": true
15  }],
16  ...
17}

Now, identity has international friendly field names of region and postal_code instead of zip and state as well as a ISO-3166-1 alpha-2 country field. Address data fields (city, region, street, postal_code, and country) are now nullable and are returned with a null value when they aren’t available rather than as an empty string. The identity object is now available on the "owners" key of the account, which represents ownership of specific accounts.

1"accounts": [{
2  ...
3  "owners": [{
4    "addresses": [{
5      "data": {
6        "city": "Malakoff",
7        "region": "NY",
8        "street": "2992 Cameron Road",
9        "postal_code": "14236",
10        "country": "US",
11      },
12      "primary": true
13    }]
14  }],
15  ...
16}]
Transactions

When no transactions are returned from a request, the transactions object will now be null rather than an empty array.

In addition, the same changes to Identity were also made to Transactions.

1"transactions": [{
2  ...
3  "location": {
4    "address": "300 Post St",
5    "city": "San Francisco",
6    "state": "CA",
7    "zip": "94108",
8    "lat": null,
9    "lon": null
10  },
11  ...
12]}
1"transactions": [{
2  ...
3  "location": {
4    "address": "300 Post St",
5    "city": "San Francisco",
6    "region": "CA",
7    "postal_code": "94108",
8    "country": "US",
9    "lat": null,
10    "lon": null
11  },
12  ...
13]}
Institutions

Changes to the institutions schema effects responses from all of the institutions API endpoints:

The previous version of the Institution schema did not include the country of the institution as part of the response.

1"institution": {
2  "credentials": [{
3    "label": "User ID",
4    "name": "username",
5    "type": "text"
6    }, {
7    "label": "Password",
8    "name": "password",
9    "type": "password"
10  }],
11  "has_mfa": true,
12  "institution_id": "ins_109512",
13  "mfa": [
14    "code",
15    "list",
16    "questions",
17    "selections"
18  ],
19  "name": "Houndstooth Bank",
20  "products": [
21    "auth",
22    "balance",
23    "identity",
24    "transactions"
25  ],
26  // included when options.include_status is true
27  "status": {object}
28}
1"institution": {
2  "country_codes": ["US"],
3  "credentials": [{
4    "label": "User ID",
5    "name": "username",
6    "type": "text"
7    }, {
8    "label": "Password",
9    "name": "password",
10    "type": "password"
11  }],
12  "has_mfa": true,
13  "institution_id": "ins_109512",
14  "mfa": [
15    "code",
16    "list",
17    "questions",
18    "selections"
19  ],
20  "name": "Houndstooth Bank",
21  "products": [
22    "auth",
23    "balance",
24    "identity",
25    "transactions"
26  ],
27  // included when options.include_status is true
28  "status": {object}
29}

Version 2018-05-22

  • The Auth numbers schema has changed to support ACH (US-based) and EFT (Canadian-based) account numbers
  • Added the iso_currency_code and unofficial_currency_code fields to all Accounts and Transactions responses

Enable support for Canadian institutions from the Dashboard and then test in the Sandbox using the test Canadian institution, Tartan-Dominion Bank of Canada (institution ID ins_43).

Before, numbers was a list of objects, each one representing the account and routing number for an ACH-eligible US checking or savings account:

1"numbers": [{
2  "account": "9900009606",
3  "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
4  "routing": "011401533",
5  "wire_routing": "021000021"
6}]

New Auth response (2018-05-22 version)

Now, numbers can have either ach (US accounts) or eft (Canadian accounts) numbers. Note that the schema for ach numbers and eft numbers are different from one another.

1"numbers": {
2   "ach": [{
3    "account": "9900009606",
4    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
5    "routing": "011401533",
6    "wire_routing": "021000021"
7   }],
8   "eft": []
9}
1"numbers": {
2   "ach":[],
3   "eft":[{
4    "account": "111122223333",
5    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
6    "institution": "021",
7    "branch": "01140"
8   }]
9}

Version 2017-03-08

The 2017-03-08 version was the first versioned release of the API.

identity verification webhooks

Webhooks

Subscribe to events and get real-time alerts for changes

Once you have Link with Identity Verification embedded in your app, you should be able to complete an entire session and review it in the dashboard.

To complete your integration, you need to add a webhook receiver endpoint to your application.

To add a webhook, visit the dashboard webhook configuration page and click New Webhook. Note that this is the only setting used to configure Identity Verification webhook receivers; webhook URLs set via /link/token/create will not be used.

You can select which events you want to subscribe to. For Identity Verification, there are three events:

Enter your webhook receiver endpoint for the webhook you wish to subscribe to and click Save. Plaid will now send an HTTP POST request to the webhook receiver endpoint every time the event occurs, in both the Sandbox and Production environments. If multiple webhook receiver endpoints are configured for an Identity Verification event, webhooks will be sent to all the configured endpoints.

Event ordering

Identity Verification does not guarantee that webhooks will be delivered in any particular order. For example, while the logical ordering of webhooks for a Identity Verification session might look like this:

  1. STEP_UPDATED The user has started the Identity Verification session and is on the first step
  2. STEP_UPDATED
  3. STATUS_UPDATED The user has reached a terminal state for their session
  4. RETRIED A retry has been requested for this user, either via the dashboard or via API
  5. STEP_UPDATED
  6. STEP_UPDATED
  7. STATUS_UPDATED The retry has been completed

you should be prepared to handle these events in any delivery order. For example, consider whether your application will properly handle:

  • A STEP_UPDATED event being delivered after a STATUS_UPDATED event.
  • A STEP_UPDATED event being delivered before an associated RETRIED

In order to properly handle webhook events being delivered out of order, your application should lookup the user's associated session(s) via the /identity_verification/list API.

Webhook Reference

For full webhook information, refer to the API Documentation.

errors oauth

OAuth Errors

Guide to troubleshooting OAuth errors

For information on troubleshooting OAuth errors in Link not related to a specific error code, see Link troubleshooting and troubleshooting common OAuth problems.

INCORRECT_OAUTH_NONCE

An incorrect OAuth nonce was supplied when re-initializing Link.
Common causes
  • During the OAuth flow, Link must be initialized, the user must be handed off to the institution's OAuth authorization page, and then Link must be re-initialized for the user to complete Link flow. This error can occur if a different nonce is supplied during the re-initialization process than was originally supplied to Link for the first initialization step.
Troubleshooting steps
1http code 400
2{
3 "error_type": "OAUTH_ERROR",
4 "error_code": "INCORRECT_OAUTH_NONCE",
5 "error_message": "nonce does not match",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

INCORRECT_LINK_TOKEN

An incorrect Link token was supplied when re-initializing Link.
Common causes
  • During the OAuth flow, Link must be initialized, the user must be handed off to the institution's OAuth authorization page, and then Link must be re-initialized for the user to complete Link flow. This error can occur if a different link_token is supplied during the re-initialization process than was originally supplied to Link for the first initialization step.
Troubleshooting steps
1http code 400
2{
3 "error_type": "OAUTH_ERROR",
4 "error_code": "INCORRECT_LINK_TOKEN",
5 "error_message": "link token does not match original link token",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

OAUTH_STATE_ID_ALREADY_PROCESSED

The OAuth state has already been processed.
Common causes
  • During the OAuth flow, Link must be initialized, the user must be handed off to the institution's OAuth authorization page, and then Link must be re-initialized for the user to complete Link flow. This error can occur if the OAuth state ID used during re-initialization of Link has already been used.
Troubleshooting steps
1http code 208
2{
3 "error_type": "OAUTH_ERROR",
4 "error_code": "OAUTH_STATE_ID_ALREADY_PROCESSED",
5 "error_message": null,
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

OAUTH_STATE_ID_NOT_FOUND

The OAuth state id could not be found.
1http code 404
2{
3 "error_type": "OAUTH_ERROR",
4 "error_code": "OAUTH_STATE_ID_NOT_FOUND",
5 "error_message": "the provided oauth_state_id wasn't found",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}
Was this helpful?

api products monitor

Monitor

API reference for Monitor endpoints and webhooks

Endpoints
/watchlist_screening/individual/createCreate a watchlist screening for a person
/watchlist_screening/individual/getRetrieve an individual watchlist screening
/watchlist_screening/individual/listList individual watchlist screenings
/watchlist_screening/individual/updateUpdate individual watchlist screening
/watchlist_screening/individual/history/listList history for entity watchlist screenings
/watchlist_screening/individual/review/createCreate a review for an individual watchlist screening
/watchlist_screening/individual/review/listList reviews for individual watchlist screenings
/watchlist_screening/individual/hit/listList hits for individual watchlist screenings
/watchlist_screening/individual/program/getGet individual watchlist screening programs
/watchlist_screening/individual/program/listList individual watchlist screening programs
/watchlist_screening/entity/createCreate a watchlist screening for an entity
/watchlist_screening/entity/getRetrieve an individual watchlist screening
/watchlist_screening/entity/listList individual watchlist screenings
/watchlist_screening/entity/updateUpdate individual watchlist screening
/watchlist_screening/entity/history/listList history for individual watchlist screenings
/watchlist_screening/entity/review/createCreate a review for an individual watchlist screening
/watchlist_screening/entity/review/listList reviews for individual watchlist screenings
/watchlist_screening/entity/hit/listList hits for individual watchlist screenings
/watchlist_screening/entity/program/getGet individual watchlist screening programs
/watchlist_screening/entity/program/listList individual watchlist screening programs
/dashboard_user/getRetrieve information about a dashboard user
/dashboard_user/listList dashboard users
Webhooks
SCREENING: STATUS_UPDATEDThe status of an individual watchlist screening has changed
ENTITY_SCREENING: STATUS_UPDATEDThe status of an entity watchlist screening has changed

Endpoints

/watchlist_screening/individual/create

Create a watchlist screening for a person

Create a new Watchlist Screening to check your customer against watchlists defined in the associated Watchlist Program. If your associated program has ongoing screening enabled, this is the profile information that will be used to monitor your customer over time.

watchlist_screening/individual/create

Request fields and example

search_terms
requiredobject
Search inputs for creating a watchlist screening
watchlist_program_id
requiredstring
ID of the associated program.
legal_name
requiredstring
The legal name of the individual being screened.

Min length: 1
date_of_birth
string
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
document_number
string
The numeric or alphanumeric identifier associated with this document.

Min length: 4
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
client_user_id
string
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
Select Language
1const request: WatchlistScreeningIndividualCreateRequest = {
2  search_terms: {
3    program_id: 'prg_2eRPsDnL66rZ7H',
4    name: 'Aleksey Potemkin',
5    date_of_birth: '1990-05-29',
6    document_number: 'C31195855',
7    country: 'US',
8  },
9  client_user_id: 'example-client-user-id-123',
10};
11
12try {
13  const response = await client.watchlistScreeningIndividualCreate(request);
14} catch (error) {
15  // handle error
16}
watchlist_screening/individual/create

Response fields and example

id
string
ID of the associated screening.
search_terms
object
Search terms for creating an individual watchlist screening
watchlist_program_id
string
ID of the associated program.
legal_name
string
The legal name of the individual being screened.

Min length: 1
date_of_birth
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
document_number
nullablestring
The numeric or alphanumeric identifier associated with this document.

Min length: 4
country
nullablestring
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
version
integer
The current version of the search terms. Starts at 1 and increments with each edit to search_terms.
assignee
nullablestring
ID of the associated user.
status
string
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible values: rejected, pending_review, cleared
client_user_id
nullablestring
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object.

Possible values: dashboard, link, api, system
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "scr_52xR9LKo77r1Np",
3  "search_terms": {
4    "watchlist_program_id": "prg_2eRPsDnL66rZ7H",
5    "legal_name": "Aleksey Potemkin",
6    "date_of_birth": "1990-05-29",
7    "document_number": "C31195855",
8    "country": "US",
9    "version": 1
10  },
11  "assignee": "54350110fedcbaf01234ffee",
12  "status": "cleared",
13  "client_user_id": "your-db-id-3b24110",
14  "audit_trail": {
15    "source": "dashboard",
16    "dashboard_user_id": "54350110fedcbaf01234ffee",
17    "timestamp": "2020-07-24T03:26:02Z"
18  },
19  "request_id": "saKrIBuEB9qJZng"
20}
Was this helpful?

/watchlist_screening/individual/get

Retrieve an individual watchlist screening

Retrieve a previously created individual watchlist screening

watchlist_screening/individual/get

Request fields and example

watchlist_screening_id
requiredstring
ID of the associated screening.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
Select Language
1const request: WatchlistScreeningIndividualGetRequest = {
2  watchlist_screening_id: 'scr_52xR9LKo77r1Np',
3};
4
5try {
6  const response = await client.watchlistScreeningIndividualGet(request);
7} catch (error) {
8  // handle error
9}
watchlist_screening/individual/get

Response fields and example

id
string
ID of the associated screening.
search_terms
object
Search terms for creating an individual watchlist screening
watchlist_program_id
string
ID of the associated program.
legal_name
string
The legal name of the individual being screened.

Min length: 1
date_of_birth
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
document_number
nullablestring
The numeric or alphanumeric identifier associated with this document.

Min length: 4
country
nullablestring
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
version
integer
The current version of the search terms. Starts at 1 and increments with each edit to search_terms.
assignee
nullablestring
ID of the associated user.
status
string
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible values: rejected, pending_review, cleared
client_user_id
nullablestring
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object.

Possible values: dashboard, link, api, system
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "scr_52xR9LKo77r1Np",
3  "search_terms": {
4    "watchlist_program_id": "prg_2eRPsDnL66rZ7H",
5    "legal_name": "Aleksey Potemkin",
6    "date_of_birth": "1990-05-29",
7    "document_number": "C31195855",
8    "country": "US",
9    "version": 1
10  },
11  "assignee": "54350110fedcbaf01234ffee",
12  "status": "cleared",
13  "client_user_id": "your-db-id-3b24110",
14  "audit_trail": {
15    "source": "dashboard",
16    "dashboard_user_id": "54350110fedcbaf01234ffee",
17    "timestamp": "2020-07-24T03:26:02Z"
18  },
19  "request_id": "saKrIBuEB9qJZng"
20}
Was this helpful?

/watchlist_screening/individual/list

List Individual Watchlist Screenings

List previously created watchlist screenings for individuals

watchlist_screening/individual/list

Request fields and example

secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
watchlist_program_id
requiredstring
ID of the associated program.
client_user_id
string
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
status
string
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible values: rejected, pending_review, cleared
assignee
string
ID of the associated user.
cursor
string
An identifier that determines which page of results you receive.
Select Language
1const request: WatchlistScreeningIndividualListRequest = {
2  watchlist_program_id: 'prg_2eRPsDnL66rZ7H',
3  client_user_id: 'example-client-user-id-123',
4};
5
6try {
7  const response = await client.watchlistScreeningIndividualList(request);
8} catch (error) {
9  // handle error
10}
watchlist_screening/individual/list

Response fields and example

watchlist_screenings
[object]
List of individual watchlist screenings
id
string
ID of the associated screening.
search_terms
object
Search terms for creating an individual watchlist screening
watchlist_program_id
string
ID of the associated program.
legal_name
string
The legal name of the individual being screened.

Min length: 1
date_of_birth
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
document_number
nullablestring
The numeric or alphanumeric identifier associated with this document.

Min length: 4
country
nullablestring
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
version
integer
The current version of the search terms. Starts at 1 and increments with each edit to search_terms.
assignee
nullablestring
ID of the associated user.
status
string
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible values: rejected, pending_review, cleared
client_user_id
nullablestring
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object.

Possible values: dashboard, link, api, system
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
next_cursor
nullablestring
An identifier that determines which page of results you receive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "watchlist_screenings": [
3    {
4      "id": "scr_52xR9LKo77r1Np",
5      "search_terms": {
6        "watchlist_program_id": "prg_2eRPsDnL66rZ7H",
7        "legal_name": "Aleksey Potemkin",
8        "date_of_birth": "1990-05-29",
9        "document_number": "C31195855",
10        "country": "US",
11        "version": 1
12      },
13      "assignee": "54350110fedcbaf01234ffee",
14      "status": "cleared",
15      "client_user_id": "your-db-id-3b24110",
16      "audit_trail": {
17        "source": "dashboard",
18        "dashboard_user_id": "54350110fedcbaf01234ffee",
19        "timestamp": "2020-07-24T03:26:02Z"
20      }
21    }
22  ],
23  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
24  "request_id": "saKrIBuEB9qJZng"
25}
Was this helpful?

/watchlist_screening/individual/update

Update individual watchlist screening

Update a specific individual watchlist screening. This endpoint can be used to add additional customer information, correct outdated information, add a reference id, assign the individual to a reviewer, and update which program it is associated with. Please note that you may not update search_terms and status at the same time since editing search_terms may trigger an automatic status change.

watchlist_screening/individual/update

Request fields and example

watchlist_screening_id
requiredstring
ID of the associated screening.
search_terms
object
Search terms for editing an individual watchlist screening
watchlist_program_id
string
ID of the associated program.
legal_name
string
The legal name of the individual being screened.

Min length: 1
date_of_birth
string
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
document_number
string
The numeric or alphanumeric identifier associated with this document.

Min length: 4
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
assignee
string
ID of the associated user.
status
string
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible values: rejected, pending_review, cleared
client_user_id
string
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
reset_fields
[string]
A list of fields to reset back to null

Possible values: assignee
Select Language
1const request: WatchlistScreeningIndividualUpdateRequest = {
2  watchlist_screening_id: 'scr_52xR9LKo77r1Np',
3  status: 'cleared',
4};
5
6try {
7  const response = await client.watchlistScreeningIndividualUpdate(request);
8} catch (error) {
9  // handle error
10}
watchlist_screening/individual/update

Response fields and example

id
string
ID of the associated screening.
search_terms
object
Search terms for creating an individual watchlist screening
watchlist_program_id
string
ID of the associated program.
legal_name
string
The legal name of the individual being screened.

Min length: 1
date_of_birth
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
document_number
nullablestring
The numeric or alphanumeric identifier associated with this document.

Min length: 4
country
nullablestring
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
version
integer
The current version of the search terms. Starts at 1 and increments with each edit to search_terms.
assignee
nullablestring
ID of the associated user.
status
string
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible values: rejected, pending_review, cleared
client_user_id
nullablestring
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object.

Possible values: dashboard, link, api, system
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "scr_52xR9LKo77r1Np",
3  "search_terms": {
4    "watchlist_program_id": "prg_2eRPsDnL66rZ7H",
5    "legal_name": "Aleksey Potemkin",
6    "date_of_birth": "1990-05-29",
7    "document_number": "C31195855",
8    "country": "US",
9    "version": 1
10  },
11  "assignee": "54350110fedcbaf01234ffee",
12  "status": "cleared",
13  "client_user_id": "your-db-id-3b24110",
14  "audit_trail": {
15    "source": "dashboard",
16    "dashboard_user_id": "54350110fedcbaf01234ffee",
17    "timestamp": "2020-07-24T03:26:02Z"
18  },
19  "request_id": "saKrIBuEB9qJZng"
20}
Was this helpful?

/watchlist_screening/individual/history/list

List history for individual watchlist screenings

List all changes to the individual watchlist screening in reverse-chronological order. If the watchlist screening has not been edited, no history will be returned.

watchlist_screening/individual/history/list

Request fields and example

secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
watchlist_screening_id
requiredstring
ID of the associated screening.
cursor
string
An identifier that determines which page of results you receive.
Select Language
1const request: WatchlistScreeningIndividualHistoryListRequest = {
2  watchlist_screening_id: 'scr_52xR9LKo77r1Np',
3};
4
5try {
6  const response = await client.watchlistScreeningIndividualHistoryList(
7    request,
8  );
9} catch (error) {
10  // handle error
11}
watchlist_screening/individual/history/list

Response fields and example

watchlist_screenings
[object]
List of individual watchlist screenings
id
string
ID of the associated screening.
search_terms
object
Search terms for creating an individual watchlist screening
watchlist_program_id
string
ID of the associated program.
legal_name
string
The legal name of the individual being screened.

Min length: 1
date_of_birth
nullablestring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
document_number
nullablestring
The numeric or alphanumeric identifier associated with this document.

Min length: 4
country
nullablestring
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
version
integer
The current version of the search terms. Starts at 1 and increments with each edit to search_terms.
assignee
nullablestring
ID of the associated user.
status
string
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible values: rejected, pending_review, cleared
client_user_id
nullablestring
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object.

Possible values: dashboard, link, api, system
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
next_cursor
nullablestring
An identifier that determines which page of results you receive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "watchlist_screenings": [
3    {
4      "id": "scr_52xR9LKo77r1Np",
5      "search_terms": {
6        "watchlist_program_id": "prg_2eRPsDnL66rZ7H",
7        "legal_name": "Aleksey Potemkin",
8        "date_of_birth": "1990-05-29",
9        "document_number": "C31195855",
10        "country": "US",
11        "version": 1
12      },
13      "assignee": "54350110fedcbaf01234ffee",
14      "status": "cleared",
15      "client_user_id": "your-db-id-3b24110",
16      "audit_trail": {
17        "source": "dashboard",
18        "dashboard_user_id": "54350110fedcbaf01234ffee",
19        "timestamp": "2020-07-24T03:26:02Z"
20      }
21    }
22  ],
23  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
24  "request_id": "saKrIBuEB9qJZng"
25}
Was this helpful?

/watchlist_screening/individual/review/create

Create a review for an individual watchlist screening

Create a review for the individual watchlist screening. Reviews are compliance reports created by users in your organization regarding the relevance of potential hits found by Plaid.

watchlist_screening/individual/review/create

Request fields and example

confirmed_hits
required[string]
Hits to mark as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected.
dismissed_hits
required[string]
Hits to mark as a false positive after thorough manual review. These hits will never recur or be updated once dismissed.
comment
string
A comment submitted by a team member as part of reviewing a watchlist screening.

Min length: 1
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
watchlist_screening_id
requiredstring
ID of the associated screening.
Select Language
1const request: WatchlistScreeningIndividualReviewCreateRequest = {
2  confirmed_hits: ['scrhit_52xR9LKo77r1Np'],
3  dismissed_hits: [],
4  watchlist_screening_id: 'scr_52xR9LKo77r1Np',
5};
6
7try {
8  const response = await client.watchlistScreeningIndividualReviewCreate(
9    request,
10  );
11} catch (error) {
12  // handle error
13}
watchlist_screening/individual/review/create

Response fields and example

id
string
ID of the associated review.
confirmed_hits
[string]
Hits marked as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected.
dismissed_hits
[string]
Hits marked as a false positive after thorough manual review. These hits will never recur or be updated once dismissed.
comment
nullablestring
A comment submitted by a team member as part of reviewing a watchlist screening.

Min length: 1
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object.

Possible values: dashboard, link, api, system
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "rev_aCLNRxK3UVzn2r",
3  "confirmed_hits": [
4    "scrhit_52xR9LKo77r1Np"
5  ],
6  "dismissed_hits": [
7    "scrhit_52xR9LKo77r1Np"
8  ],
9  "comment": "These look like legitimate matches, rejecting the customer.",
10  "audit_trail": {
11    "source": "dashboard",
12    "dashboard_user_id": "54350110fedcbaf01234ffee",
13    "timestamp": "2020-07-24T03:26:02Z"
14  },
15  "request_id": "saKrIBuEB9qJZng"
16}
Was this helpful?

/watchlist_screening/individual/review/list

List reviews for individual watchlist screenings

List all reviews for the individual watchlist screening.

watchlist_screening/individual/review/list

Request fields and example

secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
watchlist_screening_id
requiredstring
ID of the associated screening.
cursor
string
An identifier that determines which page of results you receive.
Select Language
1const request: WatchlistScreeningIndividualReviewListRequest = {
2  watchlist_screening_id: 'scr_52xR9LKo77r1Np',
3};
4
5try {
6  const response = await client.watchlistScreeningIndividualReviewList(request);
7} catch (error) {
8  // handle error
9}
watchlist_screening/individual/review/list

Response fields and example

watchlist_screening_reviews
[object]
List of screening reviews
id
string
ID of the associated review.
confirmed_hits
[string]
Hits marked as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected.
dismissed_hits
[string]
Hits marked as a false positive after thorough manual review. These hits will never recur or be updated once dismissed.
comment
nullablestring
A comment submitted by a team member as part of reviewing a watchlist screening.

Min length: 1
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object.

Possible values: dashboard, link, api, system
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
next_cursor
nullablestring
An identifier that determines which page of results you receive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "watchlist_screening_reviews": [
3    {
4      "id": "rev_aCLNRxK3UVzn2r",
5      "confirmed_hits": [
6        "scrhit_52xR9LKo77r1Np"
7      ],
8      "dismissed_hits": [
9        "scrhit_52xR9LKo77r1Np"
10      ],
11      "comment": "These look like legitimate matches, rejecting the customer.",
12      "audit_trail": {
13        "source": "dashboard",
14        "dashboard_user_id": "54350110fedcbaf01234ffee",
15        "timestamp": "2020-07-24T03:26:02Z"
16      }
17    }
18  ],
19  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
20  "request_id": "saKrIBuEB9qJZng"
21}
Was this helpful?

/watchlist_screening/individual/hit/list

List hits for individual watchlist screening

List all hits found by Plaid for a particular individual watchlist screening.

watchlist_screening/individual/hit/list

Request fields and example

secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
watchlist_screening_id
requiredstring
ID of the associated screening.
cursor
string
An identifier that determines which page of results you receive.
Select Language
1const request: WatchlistScreeningIndividualHitListRequest = {
2  watchlist_screening_id: 'scr_52xR9LKo77r1Np',
3};
4
5try {
6  const response = await client.watchlistScreeningIndividualHitList(request);
7} catch (error) {
8  // handle error
9}
watchlist_screening/individual/hit/list

Response fields and example

watchlist_screening_hits
[object]
List of individual watchlist screening hits
id
string
ID of the associated screening hit.
review_status
string
The current state of review. All watchlist screening hits begin in a pending_review state but can be changed by creating a review. When a hit is in the pending_review state, it will always show the latest version of the watchlist data Plaid has available and be compared against the latest customer information saved in the watchlist screening. Once a hit has been marked as confirmed or dismissed it will no longer be updated so that the state is as it was when the review was first conducted.

Possible values: confirmed, pending_review, dismissed
first_active
string
An ISO8601 formatted timestamp.

Format: date-time
inactive_since
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
historical_since
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
list_code
string
Shorthand identifier for a specific screening list for individuals. AU_CON: Australia Department of Foreign Affairs and Trade Consolidated List CA_CON: Government of Canada Consolidated List of Sanctions EU_CON: European External Action Service Consolidated List IZ_CIA: CIA List of Chiefs of State and Cabinet Members IZ_IPL: Interpol Red Notices for Wanted Persons List IZ_PEP: Politically Exposed Persons List IZ_UNC: United Nations Consolidated Sanctions IZ_WBK: World Bank Listing of Ineligible Firms and Individuals UK_HMC: UK HM Treasury Consolidated List US_DPL: Bureau of Industry and Security Denied Persons List US_DTC: US Department of State AECA Debarred US_FBI: US Department of Justice FBI Wanted List US_FSE: US OFAC Foreign Sanctions Evaders US_ISN: US Department of State Nonproliferation Sanctions US_PLC: US OFAC Palestinian Legislative Council US_SDN: US OFAC Specially Designated Nationals List US_SSI: US OFAC Sectoral Sanctions Identifications SG_SOF: Government of Singapore Terrorists and Terrorist Entities TR_TWL: Government of Turkey Terrorist Wanted List TR_DFD: Government of Turkey Domestic Freezing Decisions TR_FOR: Government of Turkey Foreign Freezing Requests TR_WMD: Government of Turkey Weapons of Mass Destruction TR_CMB: Government of Turkey Capital Markets Board

Possible values: AU_CON, CA_CON, EU_CON, IZ_CIA, IZ_IPL, IZ_PEP, IZ_UNC, IZ_WBK, UK_HMC, US_DPL, US_DTC, US_FBI, US_FSE, US_ISN, US_MBS, US_PLC, US_SDN, US_SSI, SG_SOF, TR_TWL, TR_DFD, TR_FOR, TR_WMD, TR_CMB
plaid_uid
string
A universal identifier for a watchlist individual that is stable across searches and updates.
source_uid
nullablestring
The identifier provided by the source sanction or watchlist. When one is not provided by the source, this is null.

Min length: 1
analysis
object
Analysis information describing why a screening hit matched the provided user information
dates_of_birth
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
documents
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
locations
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
names
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
search_terms_version
integer
The version of the screening's search_terms that were compared when the screening hit was added. screening hits are immutable once they have been reviewed. If changes are detected due to updates to the screening's search_terms, the associated program, or the list's source data prior to review, the screening hit will be updated to reflect those changes.
data
object
Information associated with the watchlist hit
dates_of_birth
[object]
Dates of birth associated with the watchlist hit
analysis
object
Summary object reflecting the match result of the associated data
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
data
object
A date range with a start and end date
beginning
string
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
ending
string
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
documents
[object]
Documents associated with the watchlist hit
analysis
object
Summary object reflecting the match result of the associated data
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
data
object
An official document, usually issued by a governing body or institution, with an associated identifier.
type
string
The kind of official document represented by this object.
birth_certificate - A certificate of birth
drivers_license - A license to operate a motor vehicle
immigration_number - Immigration or residence documents
military_id - Identification issued by a military group
other - Any document not covered by other categories
passport - An official passport issue by a government
personal_identification - Any generic personal identification that is not covered by other categories
ration_card - Identification that entitles the holder to rations
ssn - United States Social Security Number
student_id - Identification issued by an educational institution
tax_id - Identification issued for the purpose of collecting taxes
travel_document - Visas, entry permits, refugee documents, etc.
voter_id - Identification issued for the purpose of voting

Possible values: birth_certificate, drivers_license, immigration_number, military_id, other, passport, personal_identification, ration_card, ssn, student_id, tax_id, travel_document, voter_id
number
string
The numeric or alphanumeric identifier associated with this document.

Min length: 4
locations
[object]
Locations associated with the watchlist hit
analysis
object
Summary object reflecting the match result of the associated data
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
data
object
Location information for the associated individual watchlist hit
full
string
The full location string, potentially including elements like street, city, postal codes and country codes. Note that this is not necessarily a complete or well-formatted address.
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
names
[object]
Names associated with the watchlist hit
analysis
object
Summary object reflecting the match result of the associated data
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
data
object
Name information for the associated individual watchlist hit
full
string
The full name of the individual, including all parts.
is_primary
boolean
Primary names are those most commonly used to refer to this person. Only one name will ever be marked as primary.
weak_alias_determination
string
Names that are explicitly marked as low quality either by their source list, or by plaid by a series of additional checks done by Plaid. Plaid does not ever surface a hit as a result of a weak name alone. If a name has no quality issues, this value will be none.

Possible values: none, source, plaid
next_cursor
nullablestring
An identifier that determines which page of results you receive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "watchlist_screening_hits": [
3    {
4      "id": "scrhit_52xR9LKo77r1Np",
5      "review_status": "pending_review",
6      "first_active": "2020-07-24T03:26:02Z",
7      "inactive_since": "2020-07-24T03:26:02Z",
8      "historical_since": "2020-07-24T03:26:02Z",
9      "list_code": "US_SDN",
10      "plaid_uid": "uid_3NggckTimGSJHS",
11      "source_uid": "26192ABC",
12      "analysis": {
13        "dates_of_birth": "match",
14        "documents": "match",
15        "locations": "match",
16        "names": "match",
17        "search_terms_version": 1
18      },
19      "data": {
20        "dates_of_birth": [
21          {
22            "analysis": {
23              "summary": "match"
24            },
25            "data": {
26              "beginning": "1990-05-29",
27              "ending": "1990-05-29"
28            }
29          }
30        ],
31        "documents": [
32          {
33            "analysis": {
34              "summary": "match"
35            },
36            "data": {
37              "type": "passport",
38              "number": "C31195855"
39            }
40          }
41        ],
42        "locations": [
43          {
44            "analysis": {
45              "summary": "match"
46            },
47            "data": {
48              "full": "Florida, US",
49              "country": "US"
50            }
51          }
52        ],
53        "names": [
54          {
55            "analysis": {
56              "summary": "match"
57            },
58            "data": {
59              "full": "Aleksey Potemkin",
60              "is_primary": false,
61              "weak_alias_determination": "none"
62            }
63          }
64        ]
65      }
66    }
67  ],
68  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
69  "request_id": "saKrIBuEB9qJZng"
70}
Was this helpful?

/watchlist_screening/individual/program/get

Get individual watchlist screening program

Get an individual watchlist screening program

watchlist_screening/individual/program/get

Request fields and example

watchlist_program_id
requiredstring
ID of the associated program.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
Select Language
1const request: WatchlistScreeningIndividualProgramGetRequest = {
2  watchlist_program_id: 'prg_2eRPsDnL66rZ7H',
3};
4
5try {
6  const response = await client.watchlistScreeningIndividualProgramGet(request);
7} catch (error) {
8  // handle error
9}
watchlist_screening/individual/program/get

Response fields and example

id
string
ID of the associated program.
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
is_rescanning_enabled
boolean
Indicator specifying whether the program is enabled and will perform daily rescans.
lists_enabled
[string]
Watchlists enabled for the associated program

Possible values: AU_CON, CA_CON, EU_CON, IZ_CIA, IZ_IPL, IZ_PEP, IZ_UNC, IZ_WBK, UK_HMC, US_DPL, US_DTC, US_FBI, US_FSE, US_ISN, US_MBS, US_PLC, US_SDN, US_SSI, SG_SOF, TR_TWL, TR_DFD, TR_FOR, TR_WMD, TR_CMB
name
string
A name for the program to define its purpose. For example, "High Risk Individuals", "US Cardholders", or "Applicants".

Min length: 1
name_sensitivity
string
The valid name matching sensitivity configurations for a screening program. Note that while certain matching techniques may be more prevalent on less strict settings, all matching algorithms are enabled for every sensitivity.
coarse - See more potential matches. This sensitivity will see more broad phonetic matches across alphabets that make missing a potential hit very unlikely. This setting is noisier and will require more manual review.
balanced - A good default for most companies. This sensitivity is balanced to show high quality hits with reduced noise.
strict - Aggressive false positive reduction. This sensitivity will require names to be more similar than coarse and balanced settings, relying less on phonetics, while still accounting for character transpositions, missing tokens, and other common permutations.
exact - Matches must be nearly exact. This sensitivity will only show hits with exact or nearly exact name matches with only basic correction such as extraneous symbols and capitalization. This setting is generally not recommended unless you have a very specific use case.

Possible values: coarse, balanced, strict, exact
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object.

Possible values: dashboard, link, api, system
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
is_archived
boolean
Archived programs are read-only and cannot screen new customers nor participate in ongoing monitoring.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "prg_2eRPsDnL66rZ7H",
3  "created_at": "2020-07-24T03:26:02Z",
4  "is_rescanning_enabled": true,
5  "lists_enabled": [
6    "US_SDN"
7  ],
8  "name": "Sample Program",
9  "name_sensitivity": "balanced",
10  "audit_trail": {
11    "source": "dashboard",
12    "dashboard_user_id": "54350110fedcbaf01234ffee",
13    "timestamp": "2020-07-24T03:26:02Z"
14  },
15  "is_archived": false,
16  "request_id": "saKrIBuEB9qJZng"
17}
Was this helpful?

/watchlist_screening/individual/program/list

List individual watchlist screening programs

List all individual watchlist screening programs

watchlist_screening/individual/program/list

Request fields and example

secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
cursor
string
An identifier that determines which page of results you receive.
Select Language
1try {
2  const response = await client.watchlistScreeningIndividualProgramList({});
3} catch (error) {
4  // handle error
5}
watchlist_screening/individual/program/list

Response fields and example

watchlist_programs
[object]
List of individual watchlist screening programs
id
string
ID of the associated program.
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
is_rescanning_enabled
boolean
Indicator specifying whether the program is enabled and will perform daily rescans.
lists_enabled
[string]
Watchlists enabled for the associated program

Possible values: AU_CON, CA_CON, EU_CON, IZ_CIA, IZ_IPL, IZ_PEP, IZ_UNC, IZ_WBK, UK_HMC, US_DPL, US_DTC, US_FBI, US_FSE, US_ISN, US_MBS, US_PLC, US_SDN, US_SSI, SG_SOF, TR_TWL, TR_DFD, TR_FOR, TR_WMD, TR_CMB
name
string
A name for the program to define its purpose. For example, "High Risk Individuals", "US Cardholders", or "Applicants".

Min length: 1
name_sensitivity
string
The valid name matching sensitivity configurations for a screening program. Note that while certain matching techniques may be more prevalent on less strict settings, all matching algorithms are enabled for every sensitivity.
coarse - See more potential matches. This sensitivity will see more broad phonetic matches across alphabets that make missing a potential hit very unlikely. This setting is noisier and will require more manual review.
balanced - A good default for most companies. This sensitivity is balanced to show high quality hits with reduced noise.
strict - Aggressive false positive reduction. This sensitivity will require names to be more similar than coarse and balanced settings, relying less on phonetics, while still accounting for character transpositions, missing tokens, and other common permutations.
exact - Matches must be nearly exact. This sensitivity will only show hits with exact or nearly exact name matches with only basic correction such as extraneous symbols and capitalization. This setting is generally not recommended unless you have a very specific use case.

Possible values: coarse, balanced, strict, exact
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object.

Possible values: dashboard, link, api, system
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
is_archived
boolean
Archived programs are read-only and cannot screen new customers nor participate in ongoing monitoring.
next_cursor
nullablestring
An identifier that determines which page of results you receive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "watchlist_programs": [
3    {
4      "id": "prg_2eRPsDnL66rZ7H",
5      "created_at": "2020-07-24T03:26:02Z",
6      "is_rescanning_enabled": true,
7      "lists_enabled": [
8        "US_SDN"
9      ],
10      "name": "Sample Program",
11      "name_sensitivity": "balanced",
12      "audit_trail": {
13        "source": "dashboard",
14        "dashboard_user_id": "54350110fedcbaf01234ffee",
15        "timestamp": "2020-07-24T03:26:02Z"
16      },
17      "is_archived": false
18    }
19  ],
20  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
21  "request_id": "saKrIBuEB9qJZng"
22}
Was this helpful?

/watchlist_screening/entity/create

Create a watchlist screening for an entity

Create a new entity watchlist screening to check your customer against watchlists defined in the associated entity watchlist program. If your associated program has ongoing screening enabled, this is the profile information that will be used to monitor your customer over time.

watchlist_screening/entity/create

Request fields and example

search_terms
requiredobject
Search inputs for creating an entity watchlist screening
entity_watchlist_program_id
requiredstring
ID of the associated entity program.
legal_name
requiredstring
The name of the organization being screened.

Min length: 1
document_number
string
The numeric or alphanumeric identifier associated with this document.

Min length: 4
email_address
string
A valid email address.

Format: email
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
phone_number
string
A phone number in E.164 format.
url
string
An 'http' or 'https' URL (must begin with either of those).

Format: uri
client_user_id
string
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
Select Language
1const request: WatchlistScreeningEntityCreateRequest = {
2  search_terms: {
3    entity_watchlist_program_id: 'entprg_2eRPsDnL66rZ7H',
4    name: 'Example Screening Entity',
5    document_number: 'C31195855',
6    email_address: 'user@example.com',
7    country: 'US',
8    phone_number: '+14025671234',
9    url: 'https://example.com',
10  },
11  client_user_id: 'example-client-user-id-123',
12};
13
14try {
15  const response = await client.watchlistScreeningEntityCreate(request);
16} catch (error) {
17  // handle error
18}
watchlist_screening/entity/create

Response fields and example

id
string
ID of the associated entity screening.
search_terms
object
Search terms associated with an entity used for searching against watchlists
entity_watchlist_program_id
string
ID of the associated entity program.
legal_name
string
The name of the organization being screened.

Min length: 1
document_number
nullablestring
The numeric or alphanumeric identifier associated with this document.

Min length: 4
email_address
nullablestring
A valid email address.

Format: email
country
nullablestring
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
phone_number
nullablestring
A phone number in E.164 format.
url
nullablestring
An 'http' or 'https' URL (must begin with either of those).

Format: uri
version
integer
The current version of the search terms. Starts at 1 and increments with each edit to search_terms.
assignee
nullablestring
ID of the associated user.
status
string
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible values: rejected, pending_review, cleared
client_user_id
nullablestring
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object.

Possible values: dashboard, link, api, system
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "entscr_52xR9LKo77r1Np",
3  "search_terms": {
4    "entity_watchlist_program_id": "entprg_2eRPsDnL66rZ7H",
5    "legal_name": "Al-Qaida",
6    "document_number": "C31195855",
7    "email_address": "user@example.com",
8    "country": "US",
9    "phone_number": "+14025671234",
10    "url": "https://example.com",
11    "version": 1
12  },
13  "assignee": "54350110fedcbaf01234ffee",
14  "status": "cleared",
15  "client_user_id": "your-db-id-3b24110",
16  "audit_trail": {
17    "source": "dashboard",
18    "dashboard_user_id": "54350110fedcbaf01234ffee",
19    "timestamp": "2020-07-24T03:26:02Z"
20  },
21  "request_id": "saKrIBuEB9qJZng"
22}
Was this helpful?

/watchlist_screening/entity/get

Get an entity screening

Retrieve an entity watchlist screening.

watchlist_screening/entity/get

Request fields and example

entity_watchlist_screening_id
requiredstring
ID of the associated entity screening.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
Select Language
1const request: WatchlistScreeningEntityGetRequest = {
2  entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np',
3};
4
5try {
6  const response = await client.watchlistScreeningEntityGet(request);
7} catch (error) {
8  // handle error
9}
watchlist_screening/entity/get

Response fields and example

id
string
ID of the associated entity screening.
search_terms
object
Search terms associated with an entity used for searching against watchlists
entity_watchlist_program_id
string
ID of the associated entity program.
legal_name
string
The name of the organization being screened.

Min length: 1
document_number
nullablestring
The numeric or alphanumeric identifier associated with this document.

Min length: 4
email_address
nullablestring
A valid email address.

Format: email
country
nullablestring
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
phone_number
nullablestring
A phone number in E.164 format.
url
nullablestring
An 'http' or 'https' URL (must begin with either of those).

Format: uri
version
integer
The current version of the search terms. Starts at 1 and increments with each edit to search_terms.
assignee
nullablestring
ID of the associated user.
status
string
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible values: rejected, pending_review, cleared
client_user_id
nullablestring
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object.

Possible values: dashboard, link, api, system
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "entscr_52xR9LKo77r1Np",
3  "search_terms": {
4    "entity_watchlist_program_id": "entprg_2eRPsDnL66rZ7H",
5    "legal_name": "Al-Qaida",
6    "document_number": "C31195855",
7    "email_address": "user@example.com",
8    "country": "US",
9    "phone_number": "+14025671234",
10    "url": "https://example.com",
11    "version": 1
12  },
13  "assignee": "54350110fedcbaf01234ffee",
14  "status": "cleared",
15  "client_user_id": "your-db-id-3b24110",
16  "audit_trail": {
17    "source": "dashboard",
18    "dashboard_user_id": "54350110fedcbaf01234ffee",
19    "timestamp": "2020-07-24T03:26:02Z"
20  },
21  "request_id": "saKrIBuEB9qJZng"
22}
Was this helpful?

/watchlist_screening/entity/list

List entity watchlist screenings

List all entity screenings.

watchlist_screening/entity/list

Request fields and example

secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
entity_watchlist_program_id
requiredstring
ID of the associated entity program.
client_user_id
string
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
status
string
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible values: rejected, pending_review, cleared
assignee
string
ID of the associated user.
cursor
string
An identifier that determines which page of results you receive.
Select Language
1const request: WatchlistScreeningEntityListRequest = {
2  entity_watchlist_program_id: 'entprg_2eRPsDnL66rZ7H',
3};
4
5try {
6  const response = await client.watchlistScreeningEntityList(request);
7} catch (error) {
8  // handle error
9}
watchlist_screening/entity/list

Response fields and example

entity_watchlist_screenings
[object]
List of entity watchlist screening
id
string
ID of the associated entity screening.
search_terms
object
Search terms associated with an entity used for searching against watchlists
entity_watchlist_program_id
string
ID of the associated entity program.
legal_name
string
The name of the organization being screened.

Min length: 1
document_number
nullablestring
The numeric or alphanumeric identifier associated with this document.

Min length: 4
email_address
nullablestring
A valid email address.

Format: email
country
nullablestring
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
phone_number
nullablestring
A phone number in E.164 format.
url
nullablestring
An 'http' or 'https' URL (must begin with either of those).

Format: uri
version
integer
The current version of the search terms. Starts at 1 and increments with each edit to search_terms.
assignee
nullablestring
ID of the associated user.
status
string
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible values: rejected, pending_review, cleared
client_user_id
nullablestring
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object.

Possible values: dashboard, link, api, system
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
next_cursor
nullablestring
An identifier that determines which page of results you receive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "entity_watchlist_screenings": [
3    {
4      "id": "entscr_52xR9LKo77r1Np",
5      "search_terms": {
6        "entity_watchlist_program_id": "entprg_2eRPsDnL66rZ7H",
7        "legal_name": "Al-Qaida",
8        "document_number": "C31195855",
9        "email_address": "user@example.com",
10        "country": "US",
11        "phone_number": "+14025671234",
12        "url": "https://example.com",
13        "version": 1
14      },
15      "assignee": "54350110fedcbaf01234ffee",
16      "status": "cleared",
17      "client_user_id": "your-db-id-3b24110",
18      "audit_trail": {
19        "source": "dashboard",
20        "dashboard_user_id": "54350110fedcbaf01234ffee",
21        "timestamp": "2020-07-24T03:26:02Z"
22      }
23    }
24  ],
25  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
26  "request_id": "saKrIBuEB9qJZng"
27}
Was this helpful?

/watchlist_screening/entity/update

Update an entity screening

Update an entity watchlist screening.

watchlist_screening/entity/update

Request fields and example

entity_watchlist_screening_id
requiredstring
ID of the associated entity screening.
search_terms
object
Search terms for editing an entity watchlist screening
entity_watchlist_program_id
requiredstring
ID of the associated entity program.
legal_name
string
The name of the organization being screened.

Min length: 1
document_number
string
The numeric or alphanumeric identifier associated with this document.

Min length: 4
email_address
string
A valid email address.

Format: email
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
phone_number
string
A phone number in E.164 format.
url
string
An 'http' or 'https' URL (must begin with either of those).

Format: uri
assignee
string
ID of the associated user.
status
string
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible values: rejected, pending_review, cleared
client_user_id
string
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
reset_fields
[string]
A list of fields to reset back to null

Possible values: assignee
Select Language
1const request: WatchlistScreeningEntityUpdateRequest = {
2  entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np',
3  status: 'cleared',
4};
5
6try {
7  const response = await client.watchlistScreeningEntityUpdate(request);
8} catch (error) {
9  // handle error
10}
watchlist_screening/entity/update

Response fields and example

id
string
ID of the associated entity screening.
search_terms
object
Search terms associated with an entity used for searching against watchlists
entity_watchlist_program_id
string
ID of the associated entity program.
legal_name
string
The name of the organization being screened.

Min length: 1
document_number
nullablestring
The numeric or alphanumeric identifier associated with this document.

Min length: 4
email_address
nullablestring
A valid email address.

Format: email
country
nullablestring
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
phone_number
nullablestring
A phone number in E.164 format.
url
nullablestring
An 'http' or 'https' URL (must begin with either of those).

Format: uri
version
integer
The current version of the search terms. Starts at 1 and increments with each edit to search_terms.
assignee
nullablestring
ID of the associated user.
status
string
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible values: rejected, pending_review, cleared
client_user_id
nullablestring
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object.

Possible values: dashboard, link, api, system
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "entscr_52xR9LKo77r1Np",
3  "search_terms": {
4    "entity_watchlist_program_id": "entprg_2eRPsDnL66rZ7H",
5    "legal_name": "Al-Qaida",
6    "document_number": "C31195855",
7    "email_address": "user@example.com",
8    "country": "US",
9    "phone_number": "+14025671234",
10    "url": "https://example.com",
11    "version": 1
12  },
13  "assignee": "54350110fedcbaf01234ffee",
14  "status": "cleared",
15  "client_user_id": "your-db-id-3b24110",
16  "audit_trail": {
17    "source": "dashboard",
18    "dashboard_user_id": "54350110fedcbaf01234ffee",
19    "timestamp": "2020-07-24T03:26:02Z"
20  },
21  "request_id": "saKrIBuEB9qJZng"
22}
Was this helpful?

/watchlist_screening/entity/history/list

List history for entity watchlist screenings

List all changes to the entity watchlist screening in reverse-chronological order. If the watchlist screening has not been edited, no history will be returned.

watchlist_screening/entity/history/list

Request fields and example

secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
entity_watchlist_screening_id
requiredstring
ID of the associated entity screening.
cursor
string
An identifier that determines which page of results you receive.
Select Language
1const request: WatchlistScreeningEntityHistoryListRequest = {
2  entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np',
3};
4
5try {
6  const response = await client.watchlistScreeningEntityHistoryList(request);
7} catch (error) {
8  // handle error
9}
watchlist_screening/entity/history/list

Response fields and example

entity_watchlist_screenings
[object]
List of entity watchlist screening
id
string
ID of the associated entity screening.
search_terms
object
Search terms associated with an entity used for searching against watchlists
entity_watchlist_program_id
string
ID of the associated entity program.
legal_name
string
The name of the organization being screened.

Min length: 1
document_number
nullablestring
The numeric or alphanumeric identifier associated with this document.

Min length: 4
email_address
nullablestring
A valid email address.

Format: email
country
nullablestring
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
phone_number
nullablestring
A phone number in E.164 format.
url
nullablestring
An 'http' or 'https' URL (must begin with either of those).

Format: uri
version
integer
The current version of the search terms. Starts at 1 and increments with each edit to search_terms.
assignee
nullablestring
ID of the associated user.
status
string
A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible values: rejected, pending_review, cleared
client_user_id
nullablestring
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Min length: 1
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object.

Possible values: dashboard, link, api, system
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
next_cursor
nullablestring
An identifier that determines which page of results you receive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "entity_watchlist_screenings": [
3    {
4      "id": "entscr_52xR9LKo77r1Np",
5      "search_terms": {
6        "entity_watchlist_program_id": "entprg_2eRPsDnL66rZ7H",
7        "legal_name": "Al-Qaida",
8        "document_number": "C31195855",
9        "email_address": "user@example.com",
10        "country": "US",
11        "phone_number": "+14025671234",
12        "url": "https://example.com",
13        "version": 1
14      },
15      "assignee": "54350110fedcbaf01234ffee",
16      "status": "cleared",
17      "client_user_id": "your-db-id-3b24110",
18      "audit_trail": {
19        "source": "dashboard",
20        "dashboard_user_id": "54350110fedcbaf01234ffee",
21        "timestamp": "2020-07-24T03:26:02Z"
22      }
23    }
24  ],
25  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
26  "request_id": "saKrIBuEB9qJZng"
27}
Was this helpful?

/watchlist_screening/entity/review/create

Create a review for an entity watchlist screening

Create a review for an entity watchlist screening. Reviews are compliance reports created by users in your organization regarding the relevance of potential hits found by Plaid.

watchlist_screening/entity/review/create

Request fields and example

confirmed_hits
required[string]
Hits to mark as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected.
dismissed_hits
required[string]
Hits to mark as a false positive after thorough manual review. These hits will never recur or be updated once dismissed.
comment
string
A comment submitted by a team member as part of reviewing a watchlist screening.

Min length: 1
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
entity_watchlist_screening_id
requiredstring
ID of the associated entity screening.
Select Language
1const request: WatchlistScreeningEntityReviewCreateRequest = {
2  entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np',
3};
4
5try {
6  const response = await client.watchlistScreeningEntityReviewCreate(request);
7} catch (error) {
8  // handle error
9}
watchlist_screening/entity/review/create

Response fields and example

id
string
ID of the associated entity review.
confirmed_hits
[string]
Hits marked as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected.
dismissed_hits
[string]
Hits marked as a false positive after thorough manual review. These hits will never recur or be updated once dismissed.
comment
nullablestring
A comment submitted by a team member as part of reviewing a watchlist screening.

Min length: 1
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object.

Possible values: dashboard, link, api, system
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "entrev_aCLNRxK3UVzn2r",
3  "confirmed_hits": [
4    "enthit_52xR9LKo77r1Np"
5  ],
6  "dismissed_hits": [
7    "enthit_52xR9LKo77r1Np"
8  ],
9  "comment": "These look like legitimate matches, rejecting the customer.",
10  "audit_trail": {
11    "source": "dashboard",
12    "dashboard_user_id": "54350110fedcbaf01234ffee",
13    "timestamp": "2020-07-24T03:26:02Z"
14  },
15  "request_id": "saKrIBuEB9qJZng"
16}
Was this helpful?

/watchlist_screening/entity/review/list

List reviews for entity watchlist screenings

List all reviews for a particular entity watchlist screening. Reviews are compliance reports created by users in your organization regarding the relevance of potential hits found by Plaid.

watchlist_screening/entity/review/list

Request fields and example

secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
entity_watchlist_screening_id
requiredstring
ID of the associated entity screening.
cursor
string
An identifier that determines which page of results you receive.
Select Language
1const request: WatchlistScreeningEntityReviewListRequest = {
2  entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np',
3};
4
5try {
6  const response = await client.watchlistScreeningEntityReviewList(request);
7} catch (error) {
8  // handle error
9}
watchlist_screening/entity/review/list

Response fields and example

entity_watchlist_screening_reviews
[object]
List of entity watchlist screening reviews
id
string
ID of the associated entity review.
confirmed_hits
[string]
Hits marked as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected.
dismissed_hits
[string]
Hits marked as a false positive after thorough manual review. These hits will never recur or be updated once dismissed.
comment
nullablestring
A comment submitted by a team member as part of reviewing a watchlist screening.

Min length: 1
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object.

Possible values: dashboard, link, api, system
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
next_cursor
nullablestring
An identifier that determines which page of results you receive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "entity_watchlist_screening_reviews": [
3    {
4      "id": "entrev_aCLNRxK3UVzn2r",
5      "confirmed_hits": [
6        "enthit_52xR9LKo77r1Np"
7      ],
8      "dismissed_hits": [
9        "enthit_52xR9LKo77r1Np"
10      ],
11      "comment": "These look like legitimate matches, rejecting the customer.",
12      "audit_trail": {
13        "source": "dashboard",
14        "dashboard_user_id": "54350110fedcbaf01234ffee",
15        "timestamp": "2020-07-24T03:26:02Z"
16      }
17    }
18  ],
19  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
20  "request_id": "saKrIBuEB9qJZng"
21}
Was this helpful?

/watchlist_screening/entity/hit/list

List hits for entity watchlist screenings

List all hits for the entity watchlist screening.

watchlist_screening/entity/hit/list

Request fields and example

secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
entity_watchlist_screening_id
requiredstring
ID of the associated entity screening.
cursor
string
An identifier that determines which page of results you receive.
Select Language
1const request: WatchlistScreeningEntityHitListRequest = {
2  entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np',
3};
4
5try {
6  const response = await client.watchlistScreeningEntityHitList(request);
7} catch (error) {
8  // handle error
9}
watchlist_screening/entity/hit/list

Response fields and example

entity_watchlist_screening_hits
[object]
List of entity watchlist screening hits
id
string
ID of the associated entity screening hit.
review_status
string
The current state of review. All watchlist screening hits begin in a pending_review state but can be changed by creating a review. When a hit is in the pending_review state, it will always show the latest version of the watchlist data Plaid has available and be compared against the latest customer information saved in the watchlist screening. Once a hit has been marked as confirmed or dismissed it will no longer be updated so that the state is as it was when the review was first conducted.

Possible values: confirmed, pending_review, dismissed
first_active
string
An ISO8601 formatted timestamp.

Format: date-time
inactive_since
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
historical_since
nullablestring
An ISO8601 formatted timestamp.

Format: date-time
list_code
string
Shorthand identifier for a specific screening list for entities. AU_CON: Australia Department of Foreign Affairs and Trade Consolidated List CA_CON: Government of Canada Consolidated List of Sanctions EU_CON: European External Action Service Consolidated List IZ_SOE: State Owned Enterprise List IZ_UNC: United Nations Consolidated Sanctions IZ_WBK: World Bank Listing of Ineligible Firms and Individuals US_CAP: US OFAC Correspondent Account or Payable-Through Account Sanctions US_FSE: US OFAC Foreign Sanctions Evaders US_MBS: US Non-SDN Menu-Based Sanctions US_SDN: US Specially Designated Nationals List US_SSI: US OFAC Sectoral Sanctions Identifications US_CMC: US OFAC Non-SDN Chinese Military-Industrial Complex List US_UVL: Bureau of Industry and Security Unverified List UK_HMC: UK HM Treasury Consolidated List

Possible values: CA_CON, EU_CON, IZ_SOE, IZ_UNC, IZ_WBK, US_CAP, US_FSE, US_MBS, US_SDN, US_SSI, US_CMC, US_UVL, AU_CON, UK_HMC
plaid_uid
string
A universal identifier for a watchlist individual that is stable across searches and updates.
source_uid
nullablestring
The identifier provided by the source sanction or watchlist. When one is not provided by the source, this is null.

Min length: 1
analysis
object
Analysis information describing why a screening hit matched the provided entity information
documents
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
email_addresses
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
locations
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
names
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
phone_numbers
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
urls
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
search_terms_version
integer
The version of the entity screening's search_terms that were compared when the entity screening hit was added. entity screening hits are immutable once they have been reviewed. If changes are detected due to updates to the entity screening's search_terms, the associated entity program, or the list's source data prior to review, the entity screening hit will be updated to reflect those changes.
data
object
Information associated with the entity watchlist hit
documents
[object]
Documents associated with the watchlist hit
analysis
object
Summary object reflecting the match result of the associated data
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
data
object
An official document, usually issued by a governing body or institution, with an associated identifier.
type
string
The kind of official document represented by this object.
bik - Russian bank code
business_number - A number that uniquely identifies the business within a category of businesses
imo - Number assigned to the entity by the International Maritime Organization
other - Any document not covered by other categories
swift - Number identifying a bank and branch.
tax_id - Identification issued for the purpose of collecting taxes

Possible values: bik, business_number, imo, other, swift, tax_id
number
string
The numeric or alphanumeric identifier associated with this document.

Min length: 4
email_addresses
[object]
Email addresses associated with the watchlist hit
analysis
object
Summary object reflecting the match result of the associated data
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
data
object
Email address information for the associated entity watchlist hit
email_address
string
A valid email address.

Format: email
locations
[object]
Locations associated with the watchlist hit
analysis
object
Summary object reflecting the match result of the associated data
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
data
object
Location information for the associated individual watchlist hit
full
string
The full location string, potentially including elements like street, city, postal codes and country codes. Note that this is not necessarily a complete or well-formatted address.
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
names
[object]
Names associated with the watchlist hit
analysis
object
Summary object reflecting the match result of the associated data
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
data
object
Name information for the associated entity watchlist hit
full
string
The full name of the entity.
is_primary
boolean
Primary names are those most commonly used to refer to this entity. Only one name will ever be marked as primary.
weak_alias_determination
string
Names that are explicitly marked as low quality either by their source list, or by plaid by a series of additional checks done by Plaid. Plaid does not ever surface a hit as a result of a weak name alone. If a name has no quality issues, this value will be none.

Possible values: none, source, plaid
phone_numbers
[object]
Phone numbers associated with the watchlist hit
analysis
object
Summary object reflecting the match result of the associated data
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
data
object
Phone number information associated with the entity screening hit
type
string
An enum indicating whether a phone number is a phone line or a fax line.

Possible values: phone, fax
phone_number
string
A phone number in E.164 format.
urls
[object]
URLs associated with the watchlist hit
analysis
object
Summary object reflecting the match result of the associated data
summary
string
An enum indicating the match type between data provided by user and data checked against an external data source.
match indicates that the provided input data was a strong match against external data.
partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data.
no_data indicates that Plaid was unable to find external data to compare against the provided input data.
no_input indicates that Plaid was unable to perform a check because no information was provided for this field by the end user.

Possible values: match, partial_match, no_match, no_data, no_input
data
object
URLs associated with the entity screening hit
url
string
An 'http' or 'https' URL (must begin with either of those).

Format: uri
next_cursor
nullablestring
An identifier that determines which page of results you receive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "entity_watchlist_screening_hits": [
3    {
4      "id": "enthit_52xR9LKo77r1Np",
5      "review_status": "pending_review",
6      "first_active": "2020-07-24T03:26:02Z",
7      "inactive_since": "2020-07-24T03:26:02Z",
8      "historical_since": "2020-07-24T03:26:02Z",
9      "list_code": "EU_CON",
10      "plaid_uid": "uid_3NggckTimGSJHS",
11      "source_uid": "26192ABC",
12      "analysis": {
13        "documents": "match",
14        "email_addresses": "match",
15        "locations": "match",
16        "names": "match",
17        "phone_numbers": "match",
18        "urls": "match",
19        "search_terms_version": 1
20      },
21      "data": {
22        "documents": [
23          {
24            "analysis": {
25              "summary": "match"
26            },
27            "data": {
28              "type": "swift",
29              "number": "C31195855"
30            }
31          }
32        ],
33        "email_addresses": [
34          {
35            "analysis": {
36              "summary": "match"
37            },
38            "data": {
39              "email_address": "user@example.com"
40            }
41          }
42        ],
43        "locations": [
44          {
45            "analysis": {
46              "summary": "match"
47            },
48            "data": {
49              "full": "Florida, US",
50              "country": "US"
51            }
52          }
53        ],
54        "names": [
55          {
56            "analysis": {
57              "summary": "match"
58            },
59            "data": {
60              "full": "Al Qaida",
61              "is_primary": false,
62              "weak_alias_determination": "none"
63            }
64          }
65        ],
66        "phone_numbers": [
67          {
68            "analysis": {
69              "summary": "match"
70            },
71            "data": {
72              "type": "phone",
73              "phone_number": "+14025671234"
74            }
75          }
76        ],
77        "urls": [
78          {
79            "analysis": {
80              "summary": "match"
81            },
82            "data": {
83              "url": "https://example.com"
84            }
85          }
86        ]
87      }
88    }
89  ],
90  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
91  "request_id": "saKrIBuEB9qJZng"
92}
Was this helpful?

/watchlist_screening/entity/program/get

Get entity watchlist screening program

Get an entity watchlist screening program

watchlist_screening/entity/program/get

Request fields and example

entity_watchlist_program_id
requiredstring
ID of the associated entity program.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
Select Language
1const request: WatchlistScreeningEntityProgramGetRequest = {
2  entity_watchlist_program_id: 'entprg_2eRPsDnL66rZ7H',
3};
4
5try {
6  const response = await client.watchlistScreeningEntityProgramGet(request);
7} catch (error) {
8  // handle error
9}
watchlist_screening/entity/program/get

Response fields and example

id
string
ID of the associated entity program.
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
is_rescanning_enabled
boolean
Indicator specifying whether the program is enabled and will perform daily rescans.
lists_enabled
[string]
Watchlists enabled for the associated program

Possible values: CA_CON, EU_CON, IZ_SOE, IZ_UNC, IZ_WBK, US_CAP, US_FSE, US_MBS, US_SDN, US_SSI, US_CMC, US_UVL, AU_CON, UK_HMC
name
string
A name for the entity program to define its purpose. For example, "High Risk Organizations" or "Applicants".

Min length: 1
name_sensitivity
string
The valid name matching sensitivity configurations for a screening program. Note that while certain matching techniques may be more prevalent on less strict settings, all matching algorithms are enabled for every sensitivity.
coarse - See more potential matches. This sensitivity will see more broad phonetic matches across alphabets that make missing a potential hit very unlikely. This setting is noisier and will require more manual review.
balanced - A good default for most companies. This sensitivity is balanced to show high quality hits with reduced noise.
strict - Aggressive false positive reduction. This sensitivity will require names to be more similar than coarse and balanced settings, relying less on phonetics, while still accounting for character transpositions, missing tokens, and other common permutations.
exact - Matches must be nearly exact. This sensitivity will only show hits with exact or nearly exact name matches with only basic correction such as extraneous symbols and capitalization. This setting is generally not recommended unless you have a very specific use case.

Possible values: coarse, balanced, strict, exact
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object.

Possible values: dashboard, link, api, system
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
is_archived
boolean
Archived programs are read-only and cannot screen new customers nor participate in ongoing monitoring.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "entprg_2eRPsDnL66rZ7H",
3  "created_at": "2020-07-24T03:26:02Z",
4  "is_rescanning_enabled": true,
5  "lists_enabled": [
6    "EU_CON"
7  ],
8  "name": "Sample Program",
9  "name_sensitivity": "balanced",
10  "audit_trail": {
11    "source": "dashboard",
12    "dashboard_user_id": "54350110fedcbaf01234ffee",
13    "timestamp": "2020-07-24T03:26:02Z"
14  },
15  "is_archived": false,
16  "request_id": "saKrIBuEB9qJZng"
17}
Was this helpful?

/watchlist_screening/entity/program/list

List entity watchlist screening programs

List all entity watchlist screening programs

watchlist_screening/entity/program/list

Request fields and example

secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
cursor
string
An identifier that determines which page of results you receive.
Select Language
1try {
2  const response = await client.watchlistScreeningEntityProgramList({});
3} catch (error) {
4  // handle error
5}
watchlist_screening/entity/program/list

Response fields and example

entity_watchlist_programs
[object]
List of entity watchlist screening programs
id
string
ID of the associated entity program.
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
is_rescanning_enabled
boolean
Indicator specifying whether the program is enabled and will perform daily rescans.
lists_enabled
[string]
Watchlists enabled for the associated program

Possible values: CA_CON, EU_CON, IZ_SOE, IZ_UNC, IZ_WBK, US_CAP, US_FSE, US_MBS, US_SDN, US_SSI, US_CMC, US_UVL, AU_CON, UK_HMC
name
string
A name for the entity program to define its purpose. For example, "High Risk Organizations" or "Applicants".

Min length: 1
name_sensitivity
string
The valid name matching sensitivity configurations for a screening program. Note that while certain matching techniques may be more prevalent on less strict settings, all matching algorithms are enabled for every sensitivity.
coarse - See more potential matches. This sensitivity will see more broad phonetic matches across alphabets that make missing a potential hit very unlikely. This setting is noisier and will require more manual review.
balanced - A good default for most companies. This sensitivity is balanced to show high quality hits with reduced noise.
strict - Aggressive false positive reduction. This sensitivity will require names to be more similar than coarse and balanced settings, relying less on phonetics, while still accounting for character transpositions, missing tokens, and other common permutations.
exact - Matches must be nearly exact. This sensitivity will only show hits with exact or nearly exact name matches with only basic correction such as extraneous symbols and capitalization. This setting is generally not recommended unless you have a very specific use case.

Possible values: coarse, balanced, strict, exact
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
string
A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object.

Possible values: dashboard, link, api, system
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
is_archived
boolean
Archived programs are read-only and cannot screen new customers nor participate in ongoing monitoring.
next_cursor
nullablestring
An identifier that determines which page of results you receive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "entity_watchlist_programs": [
3    {
4      "id": "entprg_2eRPsDnL66rZ7H",
5      "created_at": "2020-07-24T03:26:02Z",
6      "is_rescanning_enabled": true,
7      "lists_enabled": [
8        "EU_CON"
9      ],
10      "name": "Sample Program",
11      "name_sensitivity": "balanced",
12      "audit_trail": {
13        "source": "dashboard",
14        "dashboard_user_id": "54350110fedcbaf01234ffee",
15        "timestamp": "2020-07-24T03:26:02Z"
16      },
17      "is_archived": false
18    }
19  ],
20  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
21  "request_id": "saKrIBuEB9qJZng"
22}
Was this helpful?

/dashboard_user/get

Retrieve a dashboard user

Retrieve information about a dashboard user.

dashboard_user/get

Request fields and example

dashboard_user_id
requiredstring
ID of the associated user.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
Select Language
1const request: DashboardUserGetRequest = {
2  dashboard_user_id: 'usr_1SUuwqBdK75GKi',
3};
4
5try {
6  const response = await client.dashboardUserGet(request);
7} catch (error) {
8  // handle error
9}
dashboard_user/get

Response fields and example

id
string
ID of the associated user.
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
email_address
string
A valid email address.

Format: email
status
string
The current status of the user.

Possible values: invited, active, deactivated
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "54350110fedcbaf01234ffee",
3  "created_at": "2020-07-24T03:26:02Z",
4  "email_address": "user@example.com",
5  "status": "active",
6  "request_id": "saKrIBuEB9qJZng"
7}
Was this helpful?

/dashboard_user/list

List dashboard users

List all dashboard users associated with your account.

dashboard_user/list

Request fields and example

secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
cursor
string
An identifier that determines which page of results you receive.
Select Language
1try {
2  const response = await client.dashboardUserList({});
3} catch (error) {
4  // handle error
5}
dashboard_user/list

Response fields and example

dashboard_users
[object]
List of dashboard users
id
string
ID of the associated user.
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
email_address
string
A valid email address.

Format: email
status
string
The current status of the user.

Possible values: invited, active, deactivated
next_cursor
nullablestring
An identifier that determines which page of results you receive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "dashboard_users": [
3    {
4      "id": "54350110fedcbaf01234ffee",
5      "created_at": "2020-07-24T03:26:02Z",
6      "email_address": "user@example.com",
7      "status": "active"
8    }
9  ],
10  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
11  "request_id": "saKrIBuEB9qJZng"
12}
Was this helpful?

Webhooks

SCREENING: STATUS_UPDATED

Fired when an individual screening status has changed, which can occur manually via the dashboard or during ongoing monitoring.

webhook_type
string
SCREENING
webhook_code
string
STATUS_UPDATED
screening_id
string
The ID of the associated screening.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "SCREENING",
3  "webhook_code": "STATUS_UPDATED",
4  "screening_id": "scr_52xR9LKo77r1Np",
5  "environment": "production"
6}
Was this helpful?

ENTITY_SCREENING: STATUS_UPDATED

Fired when an entity screening status has changed, which can occur manually via the dashboard or during ongoing monitoring.

webhook_type
string
ENTITY_SCREENING
webhook_code
string
STATUS_UPDATED
screening_id
string
The ID of the associated screening.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "ENTITY_SCREENING",
3  "webhook_code": "STATUS_UPDATED",
4  "screening_id": "entscr_52xR9LKo77r1Np",
5  "environment": "production"
6}
Was this helpful?

identity

Introduction to Identity

Verify users' account ownership and reduce fraud with the Identity product.

Explore API

Overview

Plaid's Identity product helps you verify users' identities by accessing information on file with their financial institution. Using Identity, you can access a user's phone number, email address, mailing address, and name. This can be used for verifying against a trusted source that information provided by the user is correct, or for prefilling account information.

Plaid provides two endpoints for Identity: /identity/get retrieves the user's name and contact information from their financial institution, while /identity/match (beta) allows you to provide a name and contact information for a user and returns a match score indicating how well that information matches the information on file with their financial institution, simplifying the process of using identity data for account ownership verification. Both endpoints can be used to reduce fraud, improve user onboarding and conversion, and to complement Know Your Customer (KYC) compliance checks.

Identity can be used to verify all major account types supported by Plaid, including checking and savings accounts, credit cards, brokerage accounts, and loans. Identity coverage can be used to verify an account before initiating an ACH transaction: 97% of Items initialized with Auth provide Identity data as well.

Depending on your use case, you may want to verify the identity of all users, or only some. For example, you might want to verify the identity of any user initiating a funds transfer, or you might only verify users who you have identified as being higher risk, based on data such as email address, location, financial institution, or activity patterns.

Plaid Identity can be combined with Plaid Identity Verification in a single workflow to provide full identity verification and fraud reduction. Identity Verification is used for KYC, to verify that the user of your app is the person they claim to be, while Identity is used to confirm that the ownership information on their linked bank or credit card account matches this verified identity.

Getting Identity data

The /identity/get endpoint provides you with several pieces of information. The name is guaranteed to be available; the email address, phone number, and address are usually available, but may be null otherwise.

Sample Identity data

Identity data returned by /identity/get includes owners' names, addresses, email addresses, and phone numbers as reported by the financial institution. In the case of an Item containing accounts with multiple owners, all owners' information will be provided. For business accounts, the account owner’s name can be that of a business.

1"owners": [
2  {
3    "addresses": [
4      {
5        "data": {
6          "city": "Malakoff",
7          "country": "US",
8          "postal_code": "14236",
9          "region": "NY",
10          "street": "2992 Cameron Road"
11        },
12        "primary": true
13      }
14    ],
15    "emails": [
16      {
17        "data": "accountholder0@example.com",
18        "primary": true,
19        "type": "primary"
20      },
21      {
22        "data": "accountholdersecondary0@example.com",
23        "primary": false,
24        "type": "secondary"
25      },
26    ],
27    "names": [
28      "Alberta Bobbeth Charleson"
29    ],
30    "phone_numbers": [
31      {
32        "data": "1112223333",
33        "primary": true,
34        "type": "home"
35      }
36    ]
37  }
38]
Typical identity fill rates by field
FieldTypical fill rate
Name>99%
Email address98%
Address93%
Phone number90%

Matching identity data

The /identity/match feature is currently in beta; reach out to your Plaid Account Manager or contact sales if you would like it enabled.

Using /identity/match, Identity data fields such as names, addresses, email addresses, and phone numbers can be matched against the owners’ identity information on connected accounts. Multiple fields are matched in a single request, and a separate score is returned for each field to indicate how closely it matched.

If you are already using Identity Verification, you can further enhance your verification process by enabling Financial Account Matching in your Identity Verification template. This feature allows you to match the data collected during KYC without having to specify the user field in your /identity/match request. To ensure accurate matching, it's important to maintain consistency in the client_user_id used for end users across all products.

Sample Identity match data

Data returned by /identity/match includes scores from matching a user's name, address, phone number, and email with the account owner's data that was present on the connected account. A score ranging from 0 to 100 is provided for each identity field. The score will be missing if the identity information was not provided in the request or unavailable at the connected account. In the case of an Item containing accounts with multiple owners, the highest matched scores are returned.

Example of how to interpret name match score
RangeMeaningExample
100Exact matchAndrew Smith, Andrew Smith
85-99Strong match, likely spelling error, nickname, or a missing middle name, prefix or suffixAndrew Smith, Andrew Simth
70-84Possible match, likely alias or nickname and spelling errorAndrew Smith, Andy Simth
50-69Unlikely match, likely relativeAndrew Smith, Betty Smith
0-49Unlikely matchAndrew Smith, Ray Charles
1{
2  "accounts": [
3    {
4      ..
5      "legal_name": {
6        "score": 90,
7        "is_nickname_match": true,
8        "is_first_name_or_last_name_match": true
9      },
10      "phone_number": {
11        "score": 100
12      },
13      "email_address": {
14        "score": 100
15      },
16      "address": {
17        "score": 100,
18        "is_postal_code_match": true
19      },
20      ..
21    },
22  ]
23}

Additional verification methods

It is recommended to provide a backup option in case a user's account ownership cannot be automatically verified. This can include additional customer due diligence using Plaid Identity Verification.

Testing Identity

Identity can be tested in Sandbox against test data without contacting Plaid. In order to test Identity against live Items in either Development or Production, you will need to first request access by submitting a product access request Support ticket explaining your use case.

/identity/match is a beta endpoint and can be tested in Sandbox using custom user accounts. Note that it is not recommended to send real user data or PII in the Sandbox environment for use with /identity/match, as Sandbox is meant for testing purposes.

Plaid provides a GitHub repo with test data for testing Identity in Sandbox, helping you test configuration options beyond those offered by the default Sandbox user. For more information on configuring custom Sandbox data, see Configuring the custom user account.

Sample app tutorial and code

For a real-life example of an app that incorporates Identity, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that fetches Identity data in order to verify identity prior to a funds transfer. The Identity code can be found in items.js.

For a tutorial walkthrough of creating a similar app, see Account funding tutorial.

Next steps

To get started building with Identity, see Add Identity to your App.

If you are using Identity as part of an account funding use case, see the Plaid Account Funding Guide for an overview of all required steps.

If you're ready to launch to Production, see the Launch checklist.